browsergym-workarena 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

browsergym/workarena/__init__.py

@@ -1,13 +1,18 @@
-__version__ = "0.2.1"
+__version__ = "0.3.0"
+
+import inspect
+import numpy as np
 
 from browsergym.core.registration import register_task
 
+from .tasks.comp_building_block import CompositionalBuildingBlockTask
 from .tasks.dashboard import __TASKS__ as DASHBOARD_TASKS
 from .tasks.form import __TASKS__ as FORM_TASKS
 from .tasks.knowledge import __TASKS__ as KB_TASKS
 from .tasks.list import __TASKS__ as LIST_TASKS
 from .tasks.navigation import __TASKS__ as NAVIGATION_TASKS
 from .tasks.service_catalog import __TASKS__ as SERVICE_CATALOG_TASKS
+from .tasks.compositional.base import CompositionalTask
 
 ALL_WORKARENA_TASKS = [
     *DASHBOARD_TASKS,
@@ -17,6 +22,13 @@ ALL_WORKARENA_TASKS = [
     *NAVIGATION_TASKS,
     *SERVICE_CATALOG_TASKS,
 ]
+ATOMIC_TASKS = [
+    task
+    for task in ALL_WORKARENA_TASKS
+    if inspect.isclass(task)
+    and not issubclass(task, CompositionalTask)
+    and not issubclass(task, CompositionalBuildingBlockTask)
+]
 
 # register the WorkArena benchmark
 for task in ALL_WORKARENA_TASKS:

browsergym/workarena/api/category.py

@@ -0,0 +1,74 @@
+import warnings
+from faker import Faker
+
+fake = Faker()
+
+from .utils import table_api_call
+
+from ..instance import SNowInstance
+
+
+def create_category(
+    instance: SNowInstance,
+    list_name: str,
+    category_name: str = None,
+) -> list[str]:
+    """
+    NOTE: This function creates a new category in the given list. Because categories are in a drop-down list, adding more
+    categories will make the list longer and this will affect the difficulty of the task. Use only if you are certain you know
+    what you are doing.
+
+    Create a category for a given list
+
+    Parameters:
+    -----------
+    instance: SNowInstance
+        The instance to create the category in
+    list_name: str
+        The name of the list to create the category for (e.g. problem, incident, etc.)
+    category_name: str
+        The name of the category to create, defaults to a random category name
+
+    Returns:
+    --------
+    category_name, sys_id
+
+    """
+    warnings.warn(
+        "This function creates a new category in the given list. Because categories are in a drop-down list, adding more "
+        "categories will make the list longer and this will affect the difficulty of the task. Use only if you are certain you know "
+        "what you are doing.",
+        UserWarning,
+    )
+
+    if category_name is None:
+        category_name = fake.word() + "-" + fake.word()
+
+    # Create category
+    category_data = {
+        "name": list_name,
+        "element": "category",
+        "value": category_name,
+    }
+    result = table_api_call(
+        instance=instance,
+        table="sys_choice",
+        json=category_data,
+        method="POST",
+        wait_for_record=True,
+    )["result"]
+
+    sys_id = result["sys_id"]
+
+    return category_name, sys_id
+
+
+def get_categories(instance, list_name):
+    """Get the name of the categories for a given list name"""
+    categories = table_api_call(
+        instance=instance,
+        table="sys_choice",
+        params={"sysparm_query": f"name={list_name}^element=category", "sysparm_fields": "value"},
+    )["result"]
+
+    return categories

browsergym/workarena/api/change_request.py

@@ -0,0 +1,87 @@
+import faker
+import numpy as np
+
+fake = faker.Faker()
+
+from datetime import datetime, timedelta
+
+from .category import get_categories
+from .utils import table_api_call
+
+from ..instance import SNowInstance
+
+
+def create_change_request(
+    instance: SNowInstance,
+    user_sys_id: str,
+    impact: int,
+    risk: int,
+    start_date: datetime = "",
+    end_date: datetime = "",
+    hashtag: str = "",
+    short_description: str = None,
+    random: np.random = None,
+) -> list[str]:
+    """
+    Create a change request
+
+    Parameters:
+    -----------
+    instance: SNowInstance
+        The instance to create the change request in
+    user_sys_id: str
+        The sys_id of the user to assign the problem to
+    impact: str
+        The impact of the change request; ranges from 1 (high) to 3 (low)
+    risk: str
+        The risk of the change request; ranges from 2 (high) to 4 (low)
+    start_date: datetime.datetime
+        The start date of the change request; empty if not set
+    end_date: datetime.datetime
+        The end date of the change request; empty if not set
+    hashtag: str
+        The name of the hashtag for the change request. If "", no hashtag will be added
+    short_description: str
+        The short description of the change request. If None, a random sentence will be generated
+    random: np.random
+        The random number generator
+
+    Returns:
+    --------
+    sys_id of the change request
+    number of the change request
+
+    """
+    if short_description is None:
+        short_description = fake.sentence(4)
+    categories = get_categories(instance=instance, list_name="change_request")
+    category = random.choice(categories)
+
+    cfg = {
+        "reason": "broken",
+        "upon_reject": "cancel",
+        "type": "emergency",
+        "state": "-5",
+        "phase": "requested",
+        "impact": str(impact),
+        "active": "true",
+        "short_description": short_description + " " + hashtag,
+        "assigned_to": user_sys_id,
+        "start_date": str(start_date),
+        "end_date": str(end_date),
+        "upon_approval": "proceed",
+        "justification": fake.sentence(),
+        "implementation_plan": fake.sentence(),
+        "phase_state": "open",
+        "risk": str(risk),
+        "cab_required": "false",
+        "category": category,
+    }
+    result = table_api_call(
+        instance=instance,
+        table="change_request",
+        method="POST",
+        json=cfg,
+    )["result"]
+
+    return result["sys_id"], result["number"]

browsergym/workarena/api/computer_asset.py

@@ -0,0 +1,90 @@
+import json
+import numpy as np
+import time
+
+from faker import Faker
+
+fake = Faker()
+
+from ..instance import SNowInstance
+from .utils import table_api_call
+
+
+def create_computer_asset(
+    instance: SNowInstance,
+    asset_tag: str,
+    warranty_expiration_date: str = None,
+    user_sys_id: str = None,
+    computer_model_info: dict = None,
+    random: np.random = None,
+):
+    """Create a hardware asset -computer model- and assign it to a user
+    Args:
+    --------
+    instance (SNowInstance):
+        The instance to create the hardware asset in
+    asset_tag (str):
+        The asset tag of the hardware asset
+    warranty_expiration_date (str):
+        The warranty expiration date of the hardware asset. If None, a random date is chosen
+    user_sys_id (str):
+        The sys_id of the user to assign the hardware asset to. If None, the hardware asset is not assigned to any user
+    computer_model_info (dict):
+        Contains the sys_id and short_description of the computer model to create the hardware asset with.
+        If None, a random computer model is chosen
+    random (np.random):
+        The random number generator
+    Returns:
+    --------
+    sys_id (str):
+        The sys_id of the created hardware asset
+    computer_model (dict):
+        The computer model information
+    warranty_expiration_date (str):
+        The warranty expiration date of the hardware asset
+    """
+
+    if computer_model_info is None:
+        # Get the sys_id of the 'Computer' category
+        computer_model_sys_id = table_api_call(
+            instance=instance,
+            table="cmdb_model_category",
+            # The cmdb_model_category is the sys_id for the hardware category; computer in this case
+            params={
+                "sysparm_query": f"name=Computer",
+                "sysparm_fields": "sys_id",
+            },
+        )["result"][0]["sys_id"]
+        # Randomly choose a computer model if needed
+        computer_models = table_api_call(
+            instance=instance,
+            table="cmdb_model",
+            # The cmdb_model_category is the sys_id for the hardware category;
+            params={
+                "sysparm_query": f"cmdb_model_category={computer_model_sys_id}",
+                "sysparm_fields": "sys_id,short_description",
+            },
+        )["result"]
+        computer_model = random.choice(computer_models)
+    if warranty_expiration_date is None:
+        # Warranty expiration date is randomly selected between 1 year ago and 1 year from now
+        warranty_expiration_date = str(fake.date_between(start_date="-1y", end_date="+1y"))
+
+    # Create hardware asset
+    hardware_result = table_api_call(
+        instance=instance,
+        table="alm_hardware",
+        data=json.dumps(
+            {
+                "assigned_to": user_sys_id,
+                "asset_tag": asset_tag,
+                "display_name": asset_tag + " - " + computer_model["short_description"],
+                "model": computer_model["sys_id"],
+                "model_category": computer_model_sys_id,
+                "warranty_expiration": warranty_expiration_date,
+            }
+        ),
+        method="POST",
+    )["result"]
+
+    return hardware_result["sys_id"], computer_model, warranty_expiration_date

browsergym/workarena/api/cost_center.py

@@ -0,0 +1,19 @@
+import warnings
+from faker import Faker
+
+fake = Faker()
+
+from .utils import table_api_call
+
+from ..instance import SNowInstance
+
+
+def get_cost_center_sysid(instance, cost_center_name):
+    """Get the sys_id of a cost center by its name"""
+    sys_id = table_api_call(
+        instance=instance,
+        table="cmn_cost_center",
+        params={"sysparm_query": f"name={cost_center_name}", "sysparm_fields": "sys_id"},
+    )["result"][0]
+
+    return sys_id

browsergym/workarena/api/expense_line.py

@@ -0,0 +1,89 @@
+import json
+import time
+
+from faker import Faker
+
+fake = Faker()
+
+from .cost_center import get_cost_center_sysid
+from .utils import table_api_call
+
+from ..instance import SNowInstance
+
+
+def create_expense_line(
+    instance: SNowInstance,
+    amount: float,
+    number: str,
+    date: str,
+    short_description: str = None,
+    expense_hashtag: str = "",
+    task_sys_id: str = None,
+    cost_center_sys_id: str = None,
+    summary_type: str = "run_business",
+    user_sys_id: str = None,
+):
+    """Create a hardware asset -computer model- and assign it to a user
+    Args:
+    --------
+    instance (SNowInstance):
+        The instance to create the hardware asset in
+    amount (float):
+        The amount of the expense line
+    number (str):
+        The number of the expense line
+    date (str):
+        The date of the expense line
+    short_description (str):
+        The short description of the expense line; if None, a random one will be generated
+    expense_hashtag (str):
+        The hashtag of the expense line (added to the short description)
+    task_sys_id (str):
+        The sys id of the task to file the expense line under
+    cost_center_sys_id (str):
+        The sys id of the cost center to file the expense line under
+    summary_type (str):
+        The summary type of the expense line (choice of "run_business", "grow_business", "transform_business")
+    user_sys_id (str):
+        The sys_id of the user to assign the hardware asset to. If None, the hardware asset is not assigned to any user
+    Returns:
+    --------
+    sys_id (str):
+        The sys_id of the created expense_line
+    expense_line_number (str):
+        The number of the created expense_line
+    """
+    if cost_center_sys_id is None:
+        # sys_id of the engineering cost center
+        cost_center_sys_id = table_api_call(
+            instance=instance,
+            table="cmn_cost_center",
+            params={"sysparm_query": "name=Engineering"},
+        )["result"][0]["sys_id"]
+
+    if short_description is None:
+        short_description = fake.sentence(4)
+
+    expense_cfg = {
+        "date": date,
+        "base_expense": "",
+        "short_description": short_description + " " + expense_hashtag,
+        "summary_type": summary_type,
+        "summary_type": "run_business",
+        "type": "one-time",
+        "number": f"{number}",
+        "task": f"{task_sys_id}",
+        "state": "processed",
+        "amount": f"{amount}",
+        "cost_center": f"{cost_center_sys_id}",
+        "user": f"{user_sys_id}",
+    }
+
+    result = table_api_call(
+        instance=instance,
+        table="fm_expense_line",
+        json=expense_cfg,
+        method="POST",
+    )["result"]
+
+    return result["sys_id"], result["number"]

browsergym/workarena/api/incident.py

@@ -0,0 +1,45 @@
+from faker import Faker
+from ..instance import SNowInstance
+
+fake = Faker()
+
+from .utils import table_api_call
+
+
+def create_incident(
+    instance: SNowInstance,
+    incident_number: int,
+    caller_sys_id: str,
+    category: str,
+    impact: int,
+    urgency: int,
+    priority: int,
+    incident_hastag: str = None,
+    assigned_to: str = None,
+):
+    incident_config = {
+        "task_effective_number": incident_number,
+        "number": incident_number,
+        "state": 2,
+        "knowledge": False,
+        "impact": impact,
+        "active": True,
+        "priority": priority,
+        "caller_id": caller_sys_id,
+        "short_description": incident_hastag if incident_hastag else " ".join(fake.words(5)),
+        "description": " ".join(fake.words(10)),
+        "incident_state": 2,
+        "urgency": urgency,
+        "severity": 3,
+        "category": category,
+    }
+    if assigned_to:
+        incident_config["assigned_to"] = assigned_to
+
+    incident_response = table_api_call(
+        instance=instance,
+        table="incident",
+        json=incident_config,
+        method="POST",
+    )["result"]
+    return incident_response

browsergym/workarena/api/knowledge.py

@@ -0,0 +1,29 @@
+from ..instance import SNowInstance
+from .utils import table_api_call
+
+
+def give_kb_read_permissions(admin_instance, user_sys_id, user_name, kb_sys_id, kb_name):
+    # Need admin permissions to give KB permissions to the user
+
+    # Create user criteria
+    user_criteria_data = {
+        "user": user_sys_id,
+        "name": f"{user_name} read KB",
+        "short_description": f"Let {user_name} read {kb_name}",
+    }
+    criteria_response = table_api_call(
+        instance=admin_instance, table="user_criteria", json=user_criteria_data, method="POST"
+    )["result"]
+    criteria_sys_id = criteria_response["sys_id"]
+
+    # Add user criteria entry to allow users to access the ADHOC KB
+    kb_uc_can_read_mtom_data = {
+        "user_criteria": criteria_sys_id,
+        "kb_knowledge_base": kb_sys_id,
+    }
+    _ = table_api_call(
+        instance=admin_instance,
+        table="kb_uc_can_read_mtom",
+        json=kb_uc_can_read_mtom_data,
+        method="POST",
+    )["result"]

browsergym/workarena/api/problem.py

@@ -0,0 +1,90 @@
+import faker
+
+fake = faker.Faker()
+
+from ..instance import SNowInstance
+from .utils import table_api_call
+
+
+def create_problem(
+    instance: SNowInstance,
+    priority: str,
+    user_sys_id: str,
+    problem_hashtag: str,
+    short_description: str = None,
+    return_number: bool = False,
+) -> list[str]:
+    """
+    Create a problem with a random cause, description, and short description. The problem is assigned to a user and
+    is created with a hashtag.
+
+    Parameters:
+    -----------
+    instance: SNowInstance
+        The instance to create the problem in
+    priority: str
+        The priority of the problem
+    user_sys_id: str
+        The sys_id of the user to assign the problem to
+    problem_hashtag: str
+        The name of the hashtag for the problem
+    short_description: str
+        The short description of the problem (optional). if not provided, a random one will be generated
+    return_number: bool
+        whether or not to return the problem number that was created
+
+    Returns:
+    --------
+    sys_id of the problem
+    problem_number (optional)
+
+    """
+    cause = fake.sentence()
+    description = fake.text()
+    if short_description is None:
+        short_description = fake.sentence(4)
+
+    # Priority is a read-only field defined by a combo of impact and urgency. The mapping is as follows:
+    # https://docs.servicenow.com/bundle/washingtondc-it-service-management/page/product/problem-management/concept/prioritise-problems.html
+    priority_to_impact_and_urgency = {
+        1: (1, 1),
+        2: (1, 2),
+        3: (1, 3),
+        4: (2, 3),
+        5: (3, 3),
+    }
+
+    impact, urgency = priority_to_impact_and_urgency[priority]
+
+    problem_cfg = {
+        "made_sla": True,
+        "upon_reject": "cancel",
+        "cause_notes": f" <p>{cause}</p> ",
+        "fix_notes": " placeholder ",  # placeholder value - will not work without a fix note
+        "knowledge": False,
+        "major_problem": False,
+        "impact": f"{impact}",
+        "active": False,
+        "sys_domain_path": "/",
+        "short_description": f"{short_description} {problem_hashtag}",
+        "known_error": False,
+        "description": f"{description}",
+        "sla_due": "2021-04-11 17:39:07",
+        "closed_at": "",
+        "resolution_code": "fix_applied",
+        "urgency": f"{urgency}",
+        "assigned_to": f"{user_sys_id}",
+        "active": True,
+    }
+
+    result = table_api_call(
+        instance=instance,
+        table="problem",
+        json=problem_cfg,
+        method="POST",
+    )["result"]
+
+    if return_number:
+        return result["sys_id"], result["number"]
+
+    return result["sys_id"]