pearmut 0.0.5__py3-none-any.whl → 0.1.0__py3-none-any.whl

pearmut/{run.py → app.py}

@@ -1,6 +1,5 @@
 import json
 import os
-import urllib
 from typing import Any
 
 from fastapi import FastAPI, Query
@@ -9,7 +8,7 @@ from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 
-from .protocols import get_next_item, log_response, reset_task
+from .protocols import get_next_item, reset_task, update_progress
 from .utils import ROOT, load_progress_data, save_progress_data
 
 os.makedirs(f"{ROOT}/data/outputs", exist_ok=True)
@@ -32,15 +31,6 @@ for campaign_id in progress_data.keys():
     with open(f"{ROOT}/data/tasks/{campaign_id}.json", "r") as f:
         tasks_data[campaign_id] = json.load(f)
 
-if tasks_data:
-    # print access dashboard URL for all campaigns
-    print(
-        list(tasks_data.values())[0]["info"]["url"] + "/dashboard.html?" + "&".join([
-            f"campaign_id={urllib.parse.quote_plus(campaign_id)}&token={campaign_data["token"]}"
-            for campaign_id, campaign_data in tasks_data.items()
-        ])
-    )
-
 
 class LogResponseRequest(BaseModel):
     campaign_id: str
@@ -61,6 +51,7 @@ async def _log_response(request: LogResponseRequest):
     if user_id not in progress_data[campaign_id]:
         return JSONResponse(content={"error": "Unknown user ID"}, status_code=400)
 
+    # append response to the output log
     with open(f"{ROOT}/data/outputs/{campaign_id}.jsonl", "a") as log_file:
         log_file.write(json.dumps(request.payload, ensure_ascii=False) + "\n")
 
@@ -77,7 +68,7 @@ async def _log_response(request: LogResponseRequest):
             for a, b in zip(times, times[1:])
         ])
 
-    log_response(campaign_id, user_id, tasks_data, progress_data, request.item_i, request.payload)
+    update_progress(campaign_id, user_id, tasks_data, progress_data, request.item_i, request.payload)
     save_progress_data(progress_data)
 
     return JSONResponse(content={"status": "ok"}, status_code=200)
@@ -214,4 +205,4 @@ app.mount(
     "/",
     StaticFiles(directory=f"{os.path.dirname(os.path.abspath(__file__))}/static/" , html=True, follow_symlink=True),
     name="static",
-)
+)

pearmut/cli.py

@@ -1,9 +1,15 @@
+"""
+Command-line interface for managing and running the Pearmut server.
+"""
+
 import argparse
 import hashlib
 import json
 import os
 import urllib.parse
 
+import psutil
+
 from .utils import ROOT, load_progress_data
 
 os.makedirs(f"{ROOT}/data/tasks", exist_ok=True)
@@ -13,39 +19,58 @@ load_progress_data(warn=None)
 def _run(args_unknown):
     import uvicorn
 
+    from .app import app, tasks_data
+
     args = argparse.ArgumentParser()
-    args.add_argument('--dev', action='store_true', help='Re-build frontend on start')
+    args.add_argument(
+        "--port", type=int, default=8001,
+        help="Port to run the server on"
+    )
+    args.add_argument(
+        "--server", default="http://localhost:8001",
+        help="Prefix server URL for protocol links"
+    )
     args = args.parse_args(args_unknown)
 
-    if args.dev:
-        # build frontend
-        from pynpm import NPMPackage
-        pkg = NPMPackage('web/package.json')
-        pkg.install()
-        pkg.run_script('build')
+    # print access dashboard URL for all campaigns
+    if tasks_data:
+        print(
+            args.server + "/dashboard.html?" + "&".join([
+                f"campaign_id={urllib.parse.quote_plus(campaign_id)}&token={campaign_data["token"]}"
+                for campaign_id, campaign_data in tasks_data.items()
+            ])
+        )
 
-    from .run import app
     uvicorn.run(
         app,
         host="127.0.0.1",
-        port=8001,
-        # reload=reload_enabled,
+        port=args.port,
+        reload=False,
         # log_level="info",
-        # app_dir="src",
-        # factory=False # factory=False means it expects 'app' to be a variable
     )
 
 
 def _add_campaign(args_unknown):
+    """
+    Add a new campaign from a JSON data file.
+    """
     import random
 
     import wonderwords
 
     args = argparse.ArgumentParser()
-    args.add_argument('data_file', type=str,
-                      help='Path to the campaign data file')
-    args.add_argument("-o", "--overwrite", action="store_true",
-                      help="Overwrite existing campaign if it exists")
+    args.add_argument(
+        'data_file', type=str,
+        help='Path to the campaign data file'
+    )
+    args.add_argument(
+        "-o", "--overwrite", action="store_true",
+        help="Overwrite existing campaign if it exists"
+    )
+    args.add_argument(
+        "--server", default="http://localhost:8001",
+        help="Prefix server URL for protocol links"
+    )
     args = args.parse_args(args_unknown)
 
     with open(args.data_file, 'r') as f:
@@ -61,13 +86,30 @@ def _add_campaign(args_unknown):
         )
         exit(1)
 
+    if "info" not in campaign_data:
+        raise ValueError("Campaign data must contain 'info' field.")
+    if "data" not in campaign_data:
+        raise ValueError("Campaign data must contain 'data' field.")
+    if "type" not in campaign_data["info"]:
+        raise ValueError("Campaign 'info' must contain 'type' field.")
+    if "template" not in campaign_data["info"]:
+        raise ValueError("Campaign 'info' must contain 'template' field.")
+
     # use random words for identifying users
     rng = random.Random(campaign_data["campaign_id"])
     rword = wonderwords.RandomWord(rng=rng)
     if campaign_data["info"]["type"] == "task-based":
         tasks = campaign_data["data"]
+        if not isinstance(tasks, list):
+            raise ValueError("Task-based campaign 'data' must be a list of tasks.")
+        if not all(isinstance(task, list) for task in tasks):
+            raise ValueError("Each task in task-based campaign 'data' must be a list of items.")
         amount = len(tasks)
     elif campaign_data["info"]["type"] == "dynamic":
+        if "num_users" not in campaign_data:
+            raise ValueError("Dynamic campaigns must specify 'num_users'.")
+        if not isinstance(campaign_data["data"], list):
+            raise ValueError("Dynamic campaign 'data' must be a list of items.")
         amount = campaign_data["num_users"]
     else:
         raise ValueError(
@@ -75,6 +117,7 @@ def _add_campaign(args_unknown):
 
     user_ids = []
     while len(user_ids) < amount:
+        # generate random user IDs
         new_id = f"{rword.random_words(amount=1, include_parts_of_speech=['adjective'])[0]}-{rword.random_words(amount=1, include_parts_of_speech=['noun'])[0]}"
         if new_id not in user_ids:
             user_ids.append(new_id)
@@ -83,11 +126,6 @@ def _add_campaign(args_unknown):
         for user_id in user_ids
     ]
 
-    server_url = campaign_data["info"].get(
-        "url",
-        "127.0.0.1:8001",  # by default local server
-    ).removesuffix("/")
-
     campaign_data["data"] = {
         user_id: task
         for user_id, task in zip(user_ids, tasks)
@@ -106,7 +144,7 @@ def _add_campaign(args_unknown):
             "time_end": None,
             "time": 0,
             "url": (
-                f"{server_url}/{campaign_data["info"]["template"]}.html"
+                f"{args.server}/{campaign_data["info"]["template"]}.html"
                 f"?campaign_id={urllib.parse.quote_plus(campaign_data['campaign_id'])}"
                 f"&user_id={user_id}"
             ),
@@ -125,7 +163,7 @@ def _add_campaign(args_unknown):
         json.dump(progress_data, f, indent=2, ensure_ascii=False)
 
     print(
-        f"{server_url}/dashboard.html"
+        f"{args.server}/dashboard.html"
         f"?campaign_id={urllib.parse.quote_plus(campaign_data['campaign_id'])}"
         f"&token={campaign_data['token']}"
     )
@@ -136,10 +174,20 @@ def _add_campaign(args_unknown):
 
 
 def main():
+    """
+    Main entry point for the CLI.
+    """
     args = argparse.ArgumentParser()
     args.add_argument('command', type=str, choices=['run', 'add', 'purge'])
     args, args_unknown = args.parse_known_args()
 
+    # enforce that only one pearmut process is running
+    for p in psutil.process_iter():
+        if "pearmut" == p.name() and p.pid != os.getpid():
+            print("Exit all running pearmut processes before running more commands.")
+            print(p)
+            exit(1)
+
     if args.command == 'run':
         _run(args_unknown)
     elif args.command == 'add':

pearmut/protocols.py

@@ -9,6 +9,9 @@ def get_next_item(
     tasks_data: dict,
     progress_data: dict,
 ) -> JSONResponse:
+    """
+    Get the next item for the user in the specified campaign.
+    """
     if tasks_data[campaign_id]["info"]["type"] == "task-based":
         return get_next_item_taskbased(campaign_id, user_id, tasks_data, progress_data)
     elif tasks_data[campaign_id]["info"]["type"] == "dynamic":
@@ -23,6 +26,9 @@ def get_next_item_taskbased(
     data_all: dict,
     progress_data: dict,
 ) -> JSONResponse:
+    """
+    Get the next item for task-based protocol.
+    """
     if all(progress_data[campaign_id][user_id]["progress"]):
         # all items completed
         # TODO: add check for data quality
@@ -51,7 +57,7 @@ def get_next_item_taskbased(
                 "total": len(data_all[campaign_id]["data"][user_id]),
             },
             "info": {
-                "status_message": data_all[campaign_id]["info"].get("status_message", ""),
+                "instructions": data_all[campaign_id]["info"].get("instructions", ""),
                 "item_i": item_i,
             } | {
                 k: v
@@ -74,6 +80,9 @@ def reset_task(
     tasks_data: dict,
     progress_data: dict,
 ) -> JSONResponse:
+    """
+    Reset the task progress for the user in the specified campaign.
+    """
     if tasks_data[campaign_id]["info"]["type"] == "task-based":
         progress_data[campaign_id][user_id]["progress"] = [False]*len(tasks_data[campaign_id]["data"][user_id])
         progress_data[campaign_id][user_id]["time"] = 0.0
@@ -89,7 +98,7 @@ def reset_task(
     
 
 
-def log_response(
+def update_progress(
     campaign_id: str,
     user_id: str,
     tasks_data: dict,
@@ -97,9 +106,13 @@ def log_response(
     item_i: int,
     payload: Any,
 ) -> JSONResponse:
+    """
+    Log the user's response for the specified item in the campaign.
+    """
     if tasks_data[campaign_id]["info"]["type"] == "task-based":
         # even if it's already set it should be fine
         progress_data[campaign_id][user_id]["progress"][item_i] = True
+        # TODO: log attention checks/quality?
         return JSONResponse(content={"status": "ok"}, status_code=200)
     elif tasks_data[campaign_id]["info"]["type"] == "dynamic":
         return JSONResponse(content={"status": "error", "message": "Dynamic protocol logging not implemented yet."}, status_code=400)

pearmut/static/assets/style.css

@@ -1,7 +1,7 @@
 body {
     margin: 0;
     padding: 0;
-    background: linear-gradient(135deg, #b9e2a1 0%, #dbcfe7 100%);
+    background: linear-gradient(135deg, #b9e2a1 0%, #e7e2cf 100%);
     background-attachment: fixed;
 }
 
@@ -14,7 +14,7 @@ body {
     width: 30%;
     background-color: #fffc;
     padding: 10px;
-    border-radius: 4px;
+    border-radius: 8px;
     vertical-align: top;
     margin-left: 5px;
 }
@@ -32,25 +32,29 @@ body {
 input[type="button"] {
     background: #fff;
     border: none;
-    border-radius: 5px;
+    border-radius: 8px;
     font-size: large;
+    box-shadow: 0 2px 4px #0001;
 }
 
-.button_navigation.button_selected {
-    background: #8db3ec !important;
-}
 
 input[type="button"]:hover:not(:disabled) {
-    background: #ffe;
+    background: #ffd;
     cursor: pointer;
 }
 
+input[type="button"]:disabled {
+    background: #bbb;
+    cursor: not-allowed;
+}
+
 label {
     user-select: none;
 }
 
 .white-box {
-    border-radius: 5pt;
+    border-radius: 8px;
     background: #fff;
     padding: 15pt;
+    box-shadow: 0 4px 6px #0000001a
 }