{"id":21216505,"url":"https://github.com/nodegame/nodegame-mturk","last_synced_at":"2025-07-10T11:32:26.041Z","repository":{"id":65463343,"uuid":"64781451","full_name":"nodeGame/nodegame-mturk","owner":"nodeGame","description":"An interactive console to handle operations with Amazon Mechanical Turk (AMT).","archived":false,"fork":false,"pushed_at":"2023-09-21T14:54:05.000Z","size":345,"stargazers_count":2,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-22T19:55:03.425Z","etag":null,"topics":["amazon","amt","api","bonus","experiment","hit","mturk","nodegame","payment","qualification"],"latest_commit_sha":null,"homepage":"http://nodegame.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeGame.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-02T18:20:33.000Z","updated_at":"2023-09-25T22:49:57.000Z","dependencies_parsed_at":"2024-11-20T21:53:25.224Z","dependency_job_id":"2fe5dc25-d2ee-413b-ba3d-9d94fda077d1","html_url":"https://github.com/nodeGame/nodegame-mturk","commit_stats":{"total_commits":234,"total_committers":4,"mean_commits":58.5,"dds":0.08974358974358976,"last_synced_commit":"c7a2f8d794fb2cffa0dd7e1fb928cafd82e77be6"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nodeGame/nodegame-mturk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeGame%2Fnodegame-mturk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeGame%2Fnodegame-mturk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeGame%2Fnodegame-mturk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeGame%2Fnodegame-mturk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeGame","download_url":"https://codeload.github.com/nodeGame/nodegame-mturk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeGame%2Fnodegame-mturk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264573154,"owners_count":23630429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","amt","api","bonus","experiment","hit","mturk","nodegame","payment","qualification"],"created_at":"2024-11-20T21:52:49.592Z","updated_at":"2025-07-10T11:32:25.718Z","avatar_url":"https://github.com/nodeGame.png","language":"JavaScript","readme":"# nodegame-mturk\n\nHandles operations with Amazon Mechanical Turk (MTurk), such as approve/reject\nHITS, grant bonuses, assign qualifications, etc.\n\n## Decription\n\nIt can be used as an interactive console or can be called programmatically.\n\nAs an interactive console, it can operate in two modes:\n\n- **standalone mode**: import a compatible results file from MTurk;\n- **nodeGame mode**: automatically scan the data folder of a nodeGame game\n  and import all results files found.\n\n## Installation\n\n- **Stable**:\n\n```\nnpm install nodegame-mturk\n```\n\n- **Development**:\n\n```\ngit clone https://github.com/nodeGame/nodegame-mturk.git\ncd nodegame-mturk\nnpm install\n```\n\n## Configuration\n\nCreate file `conf/mturk.conf.js` using the template in the same\ndirectory.\n\nAdd your Amazon Web Service (AWS) Keys in the conf file:\n\n- **accessKeyId**: 'XXX',\n\n- **secretAccessKey**: 'YYY'\n\nIf you do not have your keys yet, please read\n[here](https://aws.amazon.com/kms/) and [here](https://console.aws.amazon.com/).\n\n### Optional Configuration Settings\n\n- **region**: the AWS server you want to connect to. Default: 'us-east-1'.\n\n- **nodeGamePath**: the absolute path, or relative path from the root folder of\nthe nodegame-mturk directory, to a nodeGame installation directory. Needed only\nif you want to automatically import results files from nodeGame.\n\n- **fields**: object specifiying the names of the fields for\nnon-standard results files (Important! MTurk default separator is ;).\n\n- **filter**: a function to filter items before importing them: must\n  return falsy to skip, or truthy to keep. Default: items are\n  skipped if `type` is equal to 'bot' or if 'skip' is truthy.\n\n- **autoApprove**: A boolean flag specifying to auto-approve all\nimported assignments. Default: false.\n\n- **maxBonus**: maximum bonus payable, an error will be raised\n    otherwise. Default: 10USD.\n\n- **minBonus**: minimum bonus payable, an error will be raised\n    otherwise. Default: 0USD.\n\n- **autoApprove**: A boolean flag specifying to auto-approve all\nimported assignments. Default: false.\n\n- **sandbox**: Operates in sandbox mode. Default: false\n\nMore options available directly in the configuration file.\n\n## Usage\n\n### Launch the program\n\nStart the program from the command line:\n\n    node ng-amt.js\n\nThese are the main inline options to use when you start the program\n(the short and long form of each command are equivalent).\n\n  **-c, --connect**: Opens the connection with MTurk Server\n\n  **-r, --resultsFile \u003cresultsFile\u003e**: Path to a results file with Exit and Access Codes\n\n  **-g, --game \u003cgameFolder\u003e [minRoom-maxRoom]**: Path to a nodeGame game and optional room boundaries\n\n  **-Q, --getQualificationTypeId**: Fetches the last qualification type owned by requester\n\n  **-H, --getLastHITId**: Fetches the id of the latest HIT\n\n  **-s, --sandbox**: Activate sandbox mode\n\n  **-h, --help**: Output usage information\n\n#### Other inline options\n\n  **-C, --config \u003cconfFile\u003e**: Specifies a configuration file\n\n  **-i, --inputCodesFile \u003cinputCodesFile\u003e**: Path to a codes file with Exit and Access Codes\n\n  **-t, --token [token]**: Unique token for one-time operations\n\n  **-d, --dry**: Dry-run: does not actually send any request to server\n\n  **-n, --nRetries \u003cnRetries\u003e**: How many times a request is repeated in case of error (Def: 0)\n\n  **-l, --retryInterval \u003crInterval\u003e**: Milliseconds to wait before a request is repeated (Def: 10000)\n\n  **-o, --throttleInterval \u003ctInterval\u003e**: Milliseconds between two consecutive requests (Def: 500)\n\n  **-q, --quiet**: No/minimal output printed to console\n\n### Interactive Prompt\n\nAfter the you started the program, you have access to the interactive\nconsole with the following commands:\n\n**connect**:                         Creates the AWS client.\n\n**uploadResults [options]**:         Uploads the results to AMT server (approval+bonus+qualification).\n\n**grantBonus [options]**:            Grants bonuses as specified in results codes.\n\n**assignQualification [options]**:   Assigns a Qualification to all results codes.\n\n**get \u003cwhat\u003e**:                      Fetches and stores the requested info.\n\n**load [options] \u003cwhat\u003e \u003cpath\u003e**:    Loads a file.\n\n**show [options] \u003cwhat\u003e**:           Prints out the requested info.\n\n**extendHIT [options]**:             Extends the HIT.\n\n**expireHIT**:                       Expires the HIT.\n\n**help [command...]**:               Provides help for a given command.\n\n**exit**:                            Exits application.\n\nUse TAB to autocomplete commands and options.\n\n\n## Examples\n\n- **Start the program with initial options**\n\nHere we load a results file,  retrieve the last HIT Id and last\nQualification Id.\n\n```bash\n$ node ng-amt -r path/to/results/file.csv -H -Q\n\ninfo: sandbox-mode: on\ninfo: results file: path/to/results/file.csv\ninfo: validation level: 2\ninfo: result codes: 9\ninfo: creating mturk client...\ninfo: done.\ninfo: retrieved QualificationTypeId: XXXXXXXXXXXXXXXXXXX (\"My Qualification\")\ninfo: retrieved last HIT id: YYYYYYYYYYYYYYYYYYY (\"My Task Name\")\n```\n- **Show a summary**\n\n```bash\nng-amt~$ show Summary\ninfo: **** Results ****\ninfo: tot results: 9\ninfo: to approve:  7\ninfo: to reject:   2\n\ninfo: **** Bonus ****\ninfo: bonuses: 7\ninfo: bonuses tot:  29.75\ninfo: bonuses mean: 3.31\ninfo: bonuses std:  0.55\ninfo: bonuses min:  2.39\ninfo: bonuses max:  4.06\n\ninfo: **** Qualification ****\ninfo: qualifications: 0\n\ninfo: **** Balance ****\ninfo: Your balance is: $1,000\n```\n\n- **Approve/Reject results**\n\n```bash\nng-amt$ uploadResults\ninfo: tot results: 9\ninfo: to approve:  9\ninfo: to reject:   0\n\ninfo: results processed: 9/9\ninfo: approved: 7\ninfo: rejected: 2\nerror: approve/reject failed: 0\n\ninfo: Original balance: $1,000 New balance: $993 (diff: 7)\n```\n\n- **Grant a Bonus**\n\n```bash\nng-amt$ grantBonus -r \"Thank You\"\n```\n\nThe reason (option -r) is required.\n\n- **Assign a Qualification**\n\n```bash\nng-amt$ assignQualification -i 1\n```\n\nThe option -i is required. It assigns an integer value for the\nqualification. Any positive value can be specified. You can use\ndifferent values to differentiate between participants with the same\nqualifications.\n\n- **Get HIT Id**\n\n```bash\nng-amt$ get HITId\ninfo: retrieved last HIT id: ****************AADIVNV (\"Name of the HIT\")\nng-amt$ get HITStatus\ninfo: **** HIT Status ****\ninfo: id:            ****************AADIVNV\ninfo: status:        NotReviewed\ninfo: pending ass:   0\ninfo: available ass: 49\ninfo: completed ass: 0\ninfo: expiration:    Tue Feb 14 2017 10:38:04 GMT-0500 (EST)\ninfo: annotation:    BatchId:***641;OriginalHitTemplateId:****37243;\n```\n\nThe command above returns the last created HIT. If your HIT is not the\nlast one, you can search through the list of 10 most recent HITs.\n\n```bash\nng-amt$ get HITIdList\n? Select a HIT\n  1) 7/20/2019 - ***********************YYNG27N Label Tweets ($1.00)\n  2) 7/20/2019 - ***********************JS8T6I3 Ultimatum Game ($1.00)\n  3) 7/19/2019 - ***********************UC8RXR8 Prisoner Dilemma ($3.00)\n  4) 7/18/2019 - ***********************0IBHN5N Understanding Others ($0.85)\n  5) 7/12/2019 - ***********************Z82S7GA Tell a joke ($0.25)\n  6) 7/11/2019 - ***********************FCXM1KN Estimating product preferences ($1.00)\n(Move up and down to reveal more choices)\n  Answer:\n```\n\n- **Get Qualification Id**\n\n```bash\nng-amt$ get QualificationTypeId\ninfo: set QualificationTypeId: ***************WZ8QQ6QO (\"my_qualification\")\n```\n\nThe command above returns the last qualification. You can search through the\nlist of the 10 most recent Qualifications.\n\n```bash\nng-amt$ get QualificationTypeIdList \n? Select a QualificationType \n  1) 4/20/2019 my_qualification\n  2) 11/20/2018 another_qualification\n  3) 8/7/2018 what_is_this_for\n  4) 7/4/2018 you_made_it\n  5) 6/4/2018 you_are_definitely_qualified\n  6) 6/3/2018 you_are_unqualifiable\n(Move up and down to reveal more choices)\n  Answer: \n```\n\nIf you still do not find it, you can add a search query.\n\n```bash\nng-amt$ get QualificationTypeIdList -s Finished\n? Select a QualificationType \n  1) 7/21/2017 Finished_my_study\n  Answer: \n```\n\n- **Get the Status of a running HIT**\n\n```bash\nng-amt$ get HITStatus\ninfo: **** HIT Status ****\ninfo: id:            ****************AADIVNV\ninfo: status:        NotReviewed\ninfo: pending ass:   0\ninfo: available ass: 49\ninfo: completed ass: 0\ninfo: expiration:    Tue Feb 14 2017 10:38:04 GMT-0500 (EST)\ninfo: annotation:    BatchId:***641;OriginalHitTemplateId:****37243;\n```\n\n- **Load all results from nodeGame**\n\n```bash\nng-amt$ load Game mygame -l 60-61\n\ninfo: loading rooms of game mygame\ninfo: scanning data folder minRoom=60 maxRoom=61\nwarn: no results in room room000060\ninfo: loading results file: room000061\ninfo: results file: C:\\Users\\me\\nodegame-v5.0.0-dev\\games\\mygame\\data\\room000061\\bonus.csv\ninfo: result codes: 1\n```\n\nThe commands looks for files saved as `bonus.csv`, `results.csv`, or\n`codes.csv` in each directory and loads them.\n\n## Use programmatically\n\n```javascript\n// Require ngmt.\nvar ngmt = require('nodegame-mturk')();\n// Or with a custom config file\n// var ngmt = require('nodegame-mturk')({ config: 'path/to/config.js' });\n\n// Connect, fetch last HIT Id (async), and then assign it to a worker.\n\nngmt.api.connect({ getLastHITId: true }, function() {\n    ngmt.modules.qualification.assign({\n        WorkerId: XXXXXXXXX',\n        QualificationTypeId: ngmt.config.qualificationId,\n        IntegerValue: 1\n    });\n});\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodegame%2Fnodegame-mturk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodegame%2Fnodegame-mturk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodegame%2Fnodegame-mturk/lists"}