{"id":50100028,"url":"https://github.com/xianneuro/narraters","last_synced_at":"2026-06-06T04:00:52.735Z","repository":{"id":358190895,"uuid":"1240334515","full_name":"xianNeuro/narRaters","owner":"xianNeuro","description":"Human-in-the-loop pipeline and web UI for narrative recall analysis (transcribe, segment, correct, parse, match, causal rate).","archived":false,"fork":false,"pushed_at":"2026-05-31T22:55:18.000Z","size":106322,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T00:19:13.651Z","etag":null,"topics":["cognitive-neuroscience","event-segmentation","flask","free-recall","human-rater","memory-research","narrative-recall","nlp","open-source","python"],"latest_commit_sha":null,"homepage":"https://xianneuro.github.io/narRaters/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xianNeuro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T02:48:47.000Z","updated_at":"2026-05-31T22:55:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xianNeuro/narRaters","commit_stats":null,"previous_names":["xianneuro/narraters"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/xianNeuro/narRaters","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xianNeuro%2FnarRaters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xianNeuro%2FnarRaters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xianNeuro%2FnarRaters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xianNeuro%2FnarRaters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xianNeuro","download_url":"https://codeload.github.com/xianNeuro/narRaters/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xianNeuro%2FnarRaters/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33968711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cognitive-neuroscience","event-segmentation","flask","free-recall","human-rater","memory-research","narrative-recall","nlp","open-source","python"],"created_at":"2026-05-23T07:01:04.545Z","updated_at":"2026-06-06T04:00:52.724Z","avatar_url":"https://github.com/xianNeuro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"static/app-icon.png\" alt=\"narRaters app icon\" width=\"128\" height=\"128\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003enarRaters\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003eTurn complex narratives into structured, reviewable data — with a web UI at every step\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eGitHub:\u003c/strong\u003e \u003ca href=\"https://github.com/xianNeuro/narRaters\"\u003egithub.com/xianNeuro/narRaters\u003c/a\u003e · \u003cstrong\u003ePyPI:\u003c/strong\u003e \u003ca href=\"https://pypi.org/project/narraters/\"\u003ev0.3.14\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/narraters/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/narraters?label=PyPI\u0026color=3775A9\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/xianNeuro/narRaters\"\u003e\u003cimg src=\"https://badgen.net/github/stars/xianNeuro/narRaters?label=stars\u0026icon=github\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-research%20%2F%20non--commercial-0969da?style=flat\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/xianNeuro/narRaters/issues\"\u003e\u003cimg src=\"https://badgen.net/github/open-issues/xianNeuro/narRaters?label=issues\u0026icon=github\" alt=\"Issues\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://xianneuro.github.io/narRaters/\"\u003e🏠 Project home\u003c/a\u003e\n  ·\n  \u003ca href=\"https://pypi.org/project/narraters/\"\u003e📦 v0.3.14\u003c/a\u003e\n  ·\n  \u003ca href=\"narRater_Tutorial.pdf\"\u003e📖 Tutorial (PDF)\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/xianNeuro/narRaters/issues\"\u003e🐛 Issues\u003c/a\u003e\n  ·\n  \u003ca href=\"#citation\"\u003e📚 Cite\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/xianNeuro/narRaters/issues/new?template=feedback\"\u003e💬 Feedback\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n**narRaters** (*narrative* + *raters*) is an open-source software on [GitHub (xianNeuro/narRaters)](https://github.com/xianNeuro/narRaters) that helps process complex narratives (e.g., audio book, text-based stories, interviews, conversations, etc.) for memory, language processing, causal reasoning, and LLM research.\n\nImagine you ran a memory study: participants listened to a story, then recalled what they remembered (spoken or typed). Before you can analyze memory, you need structured data — what happened in the story, what each person recalled, and how those pieces connect.\n\n**narRaters** helps you get there. It runs common narrative-processing steps (transcribe audio, split a story into events, clean up recall text, parse recalls into clauses, match recalls back to story events, rate causal links between events) and gives you a web interface to review and fix outputs before exporting.\n\nWorks for audio or text, stories or other long narratives (including movie annotations), and human-only or human-vs-LLM workflows.\n\n| You have… | narRaters helps you… |\n|---|---|\n| Story audio or transcript | Transcribe it and break it into numbered **events** |\n| Participant recall files | Correct spelling, split into **clauses**, and **match** each clause to story events |\n| A segmented story | **Rate causal links** between event pairs (did event A lead to event B?) |\n| Automated or AI outputs | **Screen and edit** them in the browser, then export signed-off files |\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/diagram-workflow.svg\" alt=\"Typical workflow: story side (transcribe, segment, causal rate) and recall side (correct, parse, match to story)\" width=\"920\"\u003e\n\u003c/p\u003e\n\n---\n\n\n\u003c/div\u003e\n\n## Get started in 3 steps\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"72\" align=\"center\"\u003e\u003cstrong\u003e1\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003eDownload \u0026 open\u003c/strong\u003e\u003cbr\u003eGet the \u003ca href=\"https://github.com/xianNeuro/narRaters/archive/refs/tags/v0.3.14.zip\"\u003ev0.3.14 ZIP\u003c/a\u003e, unzip, and double-click \u003ccode\u003enarRater.app\u003c/code\u003e (macOS) or \u003ccode\u003enarRaters_installer.bat\u003c/code\u003e (Windows). Needs \u003ca href=\"https://www.python.org/downloads/\"\u003ePython 3.10+\u003c/a\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e2\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003ePick your pipeline\u003c/strong\u003e\u003cbr\u003eYour browser opens to the pipeline builder. Drag in only the steps you need (e.g. segment → match → causal rate). Bundled demo data is already loaded so you can explore immediately.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cstrong\u003e3\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cstrong\u003eRun, review, export\u003c/strong\u003e\u003cbr\u003eOn the dashboard, click a cell to run a step. Open the magnifying-glass icon to inspect results, edit in the browser, and export when you are satisfied.\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp\u003e\u003cstrong\u003eOr via terminal\u003c/strong\u003e (Python 3.10+; no ZIP download). Run from the folder that contains your \u003ccode\u003edata/\u003c/code\u003e and \u003ccode\u003eoutput/\u003c/code\u003e directories (or set \u003ccode\u003eNARRATERS_PROJECT_ROOT\u003c/code\u003e to that path):\u003c/p\u003e\n\n```bash\npython --version                              # must show 3.10 or newer\npython3 -m pip install narraters --upgrade    # wait for “Successfully installed”\ncd /path/to/your/project                      # folder with data/ and output/\nnarraters serve                               # browser opens to the pipeline builder\n```\n\nThen continue with **steps 2–3** above — pick your pipeline, run steps on the dashboard, review, and export.\n\n\u003e **First time?** Follow the illustrated **[Tutorial PDF](narRater_Tutorial.pdf)** or see [Installation](#installation) and [Troubleshooting](#troubleshooting).\n\n---\n\n\n\u003c/div\u003e\n\n## See the app\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/workflow.gif\" alt=\"Animated walkthrough: building a pipeline, the dashboard status grid, and rating causal links between story events\" width=\"920\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003e① Build a pipeline \u0026nbsp;→\u0026nbsp; ② Dashboard \u0026nbsp;→\u0026nbsp; ③ Rate causal links\u003c/em\u003e\n\u003c/p\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cp\u003e\u003cstrong\u003e① Pipeline dashboard\u003c/strong\u003e\u003c/p\u003e\n      \u003cimg src=\"docs/screenshots/gif-dashboard.gif\" alt=\"Animated tour of the pipeline dashboard status grid\" width=\"100%\"\u003e\u003cbr\u003e\n      \u003csub\u003eSee every subject/story, run steps, and open results. Green = done; click a cell to process.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cp\u003e\u003cstrong\u003e② Event segmentation\u003c/strong\u003e\u003c/p\u003e\n      \u003cimg src=\"docs/screenshots/gif-event-segmentation.gif\" alt=\"Animated tour of segmenting a story into events by placing boundary bars\" width=\"100%\"\u003e\u003cbr\u003e\n      \u003csub\u003eMove the cursor through the text and click to drop boundary bars. Toggle \u003cem\u003ebinary\u003c/em\u003e or \u003cem\u003e1–5\u003c/em\u003e strength (bar colored blue→red).\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cp\u003e\u003cstrong\u003e③ Recall matching\u003c/strong\u003e\u003c/p\u003e\n      \u003cimg src=\"docs/screenshots/gif-recall-matching.gif\" alt=\"Animated tour of linking recall segments to story events\" width=\"100%\"\u003e\u003cbr\u003e\n      \u003csub\u003eStory events on the left; recall segments on the right. Click a segment, then click events to match — or type event numbers. Optionally turn on \u003cem\u003eFurther ratings\u003c/em\u003e for per-segment quality checkboxes.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cp\u003e\u003cstrong\u003e④ Causal rating\u003c/strong\u003e\u003c/p\u003e\n      \u003cimg src=\"docs/screenshots/gif-causal-rating.gif\" alt=\"Animated tour of the causal rating grid\" width=\"100%\"\u003e\u003cbr\u003e\n      \u003csub\u003eClick a grid cell to rate how strongly one story event caused another (0–3 scale).\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n\n\u003c/div\u003e\n\n## Table of contents\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"#what-is-narraters\"\u003eWhat is narRaters?\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#get-started-in-3-steps\"\u003eGet started in 3 steps\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#see-the-app\"\u003eSee the app\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\n\u003cul style=\"padding-left: 0.5em;\"\u003e\n\u003cli\u003e\u003ca href=\"#zip-download-double-click-launcher\"\u003eZIP download (double-click launcher)\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#pypi-terminal\"\u003ePyPI (terminal)\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#alternate-install-command-line\"\u003eAlternate install (command line)\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#using-the-web-ui\"\u003eUsing the web UI\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#troubleshooting\"\u003eTroubleshooting\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#where-to-put-your-data\"\u003eWhere to put your data\u003c/a\u003e\n\u003cul style=\"padding-left: 0.5em;\"\u003e\n\u003cli\u003e\u003ca href=\"#example-inputoutput-data\"\u003eExample input/output data\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#pipeline-overview\"\u003ePipeline overview\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#command-line-pipeline\"\u003eCommand-line pipeline\u003c/a\u003e\n\u003cul style=\"padding-left: 0.5em;\"\u003e\n\u003cli\u003e\u003ca href=\"#step-1--transcribe-audio--text\"\u003eStep 1 — \u003ccode\u003etranscribe\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#step-2--segment-story--events\"\u003eStep 2 — \u003ccode\u003esegment\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#step-3--correct-spell--grammar-fixes\"\u003eStep 3 — \u003ccode\u003ecorrect\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#step-4--parse-recall-text--clause-level-segments\"\u003eStep 4 — \u003ccode\u003eparse\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#step-5--match-recall-segments--story-events\"\u003eStep 5 — \u003ccode\u003ematch\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#step-6--rate-causal-relationships-between-event-pairs\"\u003eStep 6 — \u003ccode\u003erate\u003c/code\u003e\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"CONTRIBUTING.md\"\u003eContributing tab\u003c/a\u003e\n\u003cul style=\"padding-left: 0.5em;\"\u003e\n\u003cli\u003e\u003ca href=\"CONTRIBUTING.md\"\u003eResearch background\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"CONTRIBUTING.md#prompt-templates\"\u003ePrompt templates\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"CONTRIBUTING.md#acknowledgements\"\u003eAcknowledgements\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"CONTRIBUTING.md#author\"\u003eAuthor\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#library--python-use\"\u003eLibrary / Python use\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#project-layout\"\u003eProject layout\u003c/a\u003e\n\u003cul style=\"padding-left: 0.5em;\"\u003e\n\u003cli\u003e\u003ca href=\"#folder-structure\"\u003eFolder structure\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#further-reading\"\u003eFurther reading\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#citation\"\u003eCitation\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#acknowledgements\"\u003eAcknowledgements\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#author\"\u003eAuthor\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\n\u003e On GitHub, **README**, **Contributing** (research background, prompt templates, acknowledgements, author), and **License** are the tabs in the bar above. Use this table of contents or the **Outline** menu (list icon, top-right) to jump between README sections.\n\n---\n\n\n\u003c/div\u003e\n\n## Installation\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nNeeds **[Python 3.10+](https://www.python.org/downloads/)**. Windows: check **“Add python.exe to PATH”** in the Python installer. If anything fails, see **[Troubleshooting](#troubleshooting)**.\n\n### ZIP download (double-click launcher)\n\n1. **[Download the ZIP (v0.3.14)](https://github.com/xianNeuro/narRaters/archive/refs/tags/v0.3.14.zip)** and unzip it — or on the [GitHub repo page](https://github.com/xianNeuro/narRaters) use green **Code ▾** → **Download ZIP** for the current `main` branch. You'll get **`narRaters-0.3.14`**, **`narRaters-main`**, or **`narRaters`** (if you used `git clone`).\n2. **Launch:** **macOS** — double-click **`narRater.app`**. **Windows** — double-click **`narRaters_installer.bat`**. **Linux** — in Terminal, `cd` into the folder and run `bash install.sh`.\n3. Your browser opens **`http://127.0.0.1:5000/pipeline-config`** with bundled examples. Put your data in **`data/`**. Restart later by double-clicking the same launcher.\n\n**macOS Gatekeeper or quarantine issues?** See **[Troubleshooting](#troubleshooting)**.\n\n### PyPI (terminal)\n\n```bash\npython --version                              # must show 3.10 or newer\npython3 -m pip install narraters --upgrade    # use python3 -m pip, not bare pip\nnarraters serve                               # browser opens to the pipeline builder\n```\n\nOn first launch, example **`data/`** and **`output/`** folders are copied into whatever directory you run from (unless you already have a project folder, or set **`NARRATERS_PROJECT_ROOT`**). Package: [`narraters`](https://pypi.org/project/narraters/) (all lowercase). For launchers and the tutorial PDF, use the ZIP install above.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull PyPI setup (venv from scratch)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npython3 --version        # must be 3.10 or newer\nmkdir -p ~/narRaters-demo \u0026\u0026 cd ~/narRaters-demo\npython3 -m venv .venv\nsource .venv/bin/activate     # Windows: .venv\\Scripts\\activate\npython3 -m pip install --upgrade pip\npython3 -m pip install narraters --upgrade\nnarraters serve\n```\n\u003c/details\u003e\n\n### Alternate install (command line)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\u003ccode\u003egit clone\u003c/code\u003e + \u003ccode\u003einstall.sh\u003c/code\u003e (project folder with bundled examples)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# macOS / Linux\ncd ~ \u0026\u0026 git clone https://github.com/xianNeuro/narRaters.git \u0026\u0026 cd narRaters \u0026\u0026 bash install.sh\n```\n\n```bat\n:: Windows\ncd %USERPROFILE% \u0026\u0026 git clone https://github.com/xianNeuro/narRaters.git \u0026\u0026 cd narRaters \u0026\u0026 narRaters_installer.bat\n```\n\nThis is what `narRater.app` does under the hood, just without the click. `git: command not found`? On macOS: `xcode-select --install`. On Windows: install [Git for Windows](https://git-scm.com/download/win).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOptional extras (Whisper, cloud APIs, local Gemma, etc.)\u003c/b\u003e\u003c/summary\u003e\n\nInside the project folder, with the venv activated:\n\n```bash\npython3 -m pip install -e \".[audio]\"     # Whisper transcription\npython3 -m pip install -e \".[api]\"       # Anthropic / OpenAI\npython3 -m pip install -e \".[nlp]\"       # spaCy segmentation\npython3 -m pip install -e \".[grammar]\"   # grammar checker\npython3 -m pip install -e \".[local-llm]\" # local Gemma\npython3 -m pip install -e \".[match]\"     # rmatch\npython3 -m pip install -e \".[all]\"       # api + match\n```\n\nPyPI users: `python3 -m pip install \"narraters[audio]\"`, etc.\n\nHeavy methods (`audio`, `local-llm`, `match`) pull multi-GB packages — the app shows a RAM/disk preflight before downloading. **Ollama (local Gemma):** install [Ollama](https://ollama.com), then `ollama pull gemma4:e4b`. **API keys:** copy `.env.example` to `.env` and edit (see [`SETUP_API.md`](SETUP_API.md)).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDevelopers\u003c/b\u003e\u003c/summary\u003e\n\n`install.sh` already does an editable install. To work on the codebase:\n\n```bash\ngit clone https://github.com/xianNeuro/narRaters.git\ncd narRaters\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate \u0026\u0026 python3 -m pip install -e .\n```\n\nBuild the standalone macOS app for icon testing: `bash packaging/macos/build_app_bundle.sh`.  Build the slim repo-root launcher: `bash packaging/macos/build_repo_app.sh`.\n\u003c/details\u003e\n\n### Using the web UI\n\nThe app runs at **`http://127.0.0.1:5000`**. First visit opens **pipeline configuration**; if you already saved a pipeline, you land on the **dashboard**.\n\n| Screen | Route | What you do there |\n|--------|--------|-------------------|\n| **Pipeline setup** | `/pipeline-config` | Drag steps into **Pipeline Flow**, set per-step **folders**, enter a **rater name** (or 🎲). **Continue** saves config and opens the dashboard. |\n| **Dashboard** | `/` | Grid: **rows** = subjects or stories, **columns** = steps. **Click a cell** to run that step (pick **method / model / prompt** when offered). **Batch** runs one step across all rows. |\n| **Detail view** | `/subject/…` or `/story/…` | **Tabs** per step for **one** row. Use the **version** dropdown to compare automated output vs your **`{id}_{ratername}-edit`** saves, then **edit** and **save**. |\n\n**Flow:** setup → dashboard (bulk runs) → open a row to **inspect, hand-correct, or compare versions**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\u003ccode\u003enarraters serve\u003c/code\u003e options\u003c/b\u003e\u003c/summary\u003e\n\n| Flag | Default | Purpose |\n|---|---|---|\n| `--port` | `5000` | Another port if `5000` is busy |\n| `--host` | `127.0.0.1` | Bind address; use `0.0.0.0` only on a **trusted** network |\n| `--no-browser` | off | Do not open a browser tab (SSH, headless) |\n| `--debug` | off | Flask debug / auto-reload while hacking on the server |\n\n```bash\nnarraters serve --port 8080 --no-browser\n```\n\u003c/details\u003e\n\nBefore a step would load **Whisper**, **Gemma via Ollama**, **rMatch**, or other heavy local models, the UI runs a **RAM / disk preflight** and may suggest a lighter method (`rules`, `test`, `clause`) if the run looks unsafe for your machine.\n\n### Troubleshooting\n\n| If you see… | Do this |\n|--------------|--------|\n| `Python 3.10+ required` | Install [Python 3.10+](https://www.python.org/downloads/), close and reopen any Terminal, run again. |\n| Blank page on `localhost:5000` | Visit **`http://127.0.0.1:5000/pipeline-config`** instead (IPv6/IPv4 quirk on some Macs). |\n| **macOS:** Gatekeeper / “cannot check for malicious software” / no **Open** in the right-click menu | **1.** In **Finder**, try **control-click** **`narRater.app`** → **Open**, then confirm **Open** if the dialog offers it — [Apple’s Gatekeeper overrides](https://support.apple.com/guide/mac-help/mh40617/mac). **2.** If that path is missing or still blocks: **System Settings** → **Privacy \u0026 Security** → scroll to **Security** — after a failed launch, macOS often shows **`narRater` was blocked** (wording varies) with **Allow Anyway** or **Open Anyway**; click it, enter your password, then launch **`narRater.app`** again (that button may only appear for a limited time after the block). **3.** Downloaded folder still quarantined: in Terminal, `xattr -dr com.apple.quarantine /path/to/narRaters-main`, then try **1** or **2** again. |\n| **macOS:** “narRater couldn't find the narRaters project folder” | macOS **App Translocation** ran the app from a temp copy. Run `xattr -dr com.apple.quarantine ~/Downloads/narRaters-main` (adjust path) and double-click again, or use [git clone install](#alternate-install-command-line). |\n| **Windows:** SmartScreen warns about `narRaters_installer.bat` | Click **More info** → **Run anyway**. |\n| Port 5000 already in use | The installer auto-tries 5001–5010 and prints the URL. To free 5000: macOS → System Settings → General → AirDrop \u0026 Handoff → turn off **AirPlay Receiver**. |\n\n---\n\n\n\u003c/div\u003e\n\n## Where to put your data\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nAfter [installation](#installation), place files so the paths match what you configured on the **pipeline** page (defaults below are relative to the **project root**). You can **remap** any step’s input/output folders there without moving data.\n\n| You have… | Put it in… | Format / naming |\n|---|---|---|\n| Story transcript (text) | `data/2_story_transcript/` | `{story}.txt` — plain UTF-8 text, one story per file |\n| Story event list (pre-segmented) | `data/3_story_events/` | `{story}_events.xlsx` — columns `event`, `story_texts` |\n| Subject recall text | `data/5_recall_texts/` | `{subj_id}.txt` — e.g. `the_siren_sub-01.txt` |\n| Story audio (optional, Step 1) | `data/1_story_audio/` | `.wav` / `.mp3` / `.m4a`, named by story |\n| Recall audio (optional, Step 1) | `data/4_recall_audio/` | `.wav` / `.mp3` / `.m4a`, named by subject |\n\nOutputs are written under `output/` — one subdirectory per step (`output/recall_corrected/`, `output/recall_parsed/`, `output/recall_rated/`, …). A smaller alternate layout lives in **`demo/data/`** (lighthouse story, three recall `.txt` files).\n\n### Example input/output data\n\nThe repository ships **realistic sample inputs and outputs** under `data/` and `output/` so you can see accepted naming and file types before adding your own study. Your private files in those folders stay untracked (see `.gitignore`); only the examples below are committed.\n\n**Stories:** **`pieman_edited`** (story audio + transcript + events) and **`the_siren`** (transcript, events, two recall subjects).\n\n| Role | Folder | Example file(s) |\n|------|--------|-----------------|\n| Story audio (input) | `data/1_story_audio/` | `pieman_edited.wav` |\n| Story transcript (input) | `data/2_story_transcript/` | `pieman_edited.txt`, `the_siren.txt` |\n| Story events (input) | `data/3_story_events/` | `pieman_edited_events.xlsx`, `the_siren_events.xlsx` |\n| Recall audio (input) | `data/4_recall_audio/` | Your own `.wav` / `.mp3` / `.m4a` / `.mp4` (not shipped publicly) |\n| Recall text (input) | `data/5_recall_texts/` | `the_siren_sub-01.txt`, `the_siren_sub-02.txt` |\n| Story transcription (output) | `output/story_audio-transcribed/` | `pieman_edited.txt` |\n| Recall transcription (output) | `output/recall_audio-transcribed/` | `the_siren_sub-01.txt`, `the_siren_sub-02.txt` |\n| Spell/grammar correction (output) | `output/recall_corrected/` | `the_siren_sub-01.txt`, `the_siren_sub-02.txt` |\n| Parsed recall (output) | `output/recall_parsed/` | `the_siren_sub-01_parsed.xlsx`, `the_siren_sub-02_parsed.xlsx` |\n| Recall ↔ events (output) | `output/recall_rated/` | `the_siren_sub-02_rate-recall-test_mode.xlsx` (method slug in filename) |\n| Causal ratings (output) | `output/causal_rated/` | `pieman_edited_causal-linguistic.xlsx`, `the_siren_causal-linguistic.xlsx` |\n\n**Quick try:** after install, point a pipeline at the default folders above and run **`sentenceCorrect` → `textParsing` → `textMatching`** on `the_siren_sub-01` / `the_siren_sub-02`, or open the bundled **`output/`** files in Excel to inspect column layouts. Story **`pieman_edited`** is useful for **`audioTranscribe`** (large `.wav`) and **`causalRating`** on `pieman_edited_events.xlsx`.\n\n**File versioning is a core feature.** Automated runs write `{subj_id}_{method}.ext` (or `{story}_…` for story-level steps); your hand-edited versions are saved as `{subj_id}_{ratername}-edit.ext` and never overwrite the originals. The web UI lets you switch between versions via a dropdown, and the `-edit` files are what you export for analysis.\n\n\n---\n\n\n\u003c/div\u003e\n\n## Pipeline overview\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n**Six optional steps — use any subset, in any order.** Each step can run automatically (rules, local models, or cloud APIs) and then be reviewed in the browser.\n\n| Plain English | Step ID | Input → output (typical) |\n|---|---|---|\n| Transcribe audio | **`audioTranscribe`** | audio file → text transcript |\n| Split story into events | **`eventSegment`** | story transcript → numbered event list |\n| Fix recall spelling/grammar | **`sentenceCorrect`** | raw recall text → corrected text |\n| Split recall into clauses | **`textParsing`** | corrected recall → clause segments |\n| Match recall to story | **`textMatching`** | recall segments + story events → rated matches |\n| Rate event causality | **`causalRating`** | story events → cause–effect ratings |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull step reference (commands \u0026amp; folders)\u003c/strong\u003e\u003c/summary\u003e\n\nIn typical recall work, **`audioTranscribe`** / **`eventSegment`** target the **story**, **`sentenceCorrect`**–**`textMatching`** each **subject recall**, and **`causalRating`** the **story event list** — but text-only projects skip Step 1, and you can equally run just **`eventSegment` + `causalRating`** or **`sentenceCorrect` → `textParsing` → `textMatching`**. Every step is available from the **GUI** or **`narraters` CLI**, has a lightweight default method, and supports hand-editing afterward.\n\n| # | Step ID | What it does | Terminal command | Default in / out |\n|---|---------|--------------|------------------|------------------|\n| 1 | **`audioTranscribe`** | Audio recordings → text (Whisper/WhisperX); story vs recall via `audioScope` or `--kind` | `narraters transcribe` | `data/4_recall_audio/` (or `data/1_story_audio/` with `--kind story`) → `output/*_audio-transcribed/` |\n| 2 | **`eventSegment`** | Story transcript → numbered events | `narraters segment` | `data/2_story_transcript/` → `data/3_story_events/` |\n| 3 | **`sentenceCorrect`** | Fix spelling/grammar in recall text (no rewriting) | `narraters correct` | `data/5_recall_texts/` → `output/recall_corrected/` |\n| 4 | **`textParsing`** | Corrected recall → clause-level segments | `narraters parse` | `output/recall_corrected/` → `output/recall_parsed/` |\n| 5 | **`textMatching`** | Recall segments ↔ story events | `narraters match` | `output/recall_parsed/` + `data/3_story_events/` → `output/recall_rated/` |\n| 6 | **`causalRating`** | Causal strength of every story-event pair | `narraters rate` | `data/3_story_events/` → `output/causal_rated/` |\n\n\u003c/details\u003e\n\nFor each step, the GUI runs the same backends as the CLI. **Available methods, flags, and examples** are under **[Command-line pipeline](#command-line-pipeline)** below.\n\n---\n\n\n\u003c/div\u003e\n\n## Command-line pipeline\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nEach of the six steps is a separate **`narraters`** subcommand with its own **`--method`** (and related options). Use the CLI for **scripts**, **clusters**, or **reproducible** runs—**with or without** the web UI, and **with any subset** of steps your study uses. General shape:\n\n```\nnarraters \u003cstep\u003e [--method METHOD] [--model MODEL] [-i INPUT] [-o OUTPUT] [--prompt-version VERSION] ...\n```\n\nDiscover what's available at any time:\n\n```bash\nnarraters --help                 # list all subcommands\nnarraters \u003cstep\u003e --help          # step-specific options\nnarraters segment --list-prompts # list available prompt versions for a step\nnarraters segment --list-models  # list supported model identifiers\n```\n\nThe method choices below are exactly those accepted by the CLI (`src/narraters/cli.py`).\n\n### Step 1 — `transcribe` (audio → text)\n\n```bash\nnarraters transcribe --model large-v3 --timestamps          # recall audio (default)\nnarraters transcribe --kind story --model small              # story audio instead\nnarraters transcribe -i path/to/audio -o path/to/out         # custom directories\nnarraters transcribe --filter sub-01                         # one item only\n```\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--model` | `tiny`, `base`, `small`, `medium`, `large-v2`, `large-v3` | Whisper model name |\n| `--timestamps` | flag | Also write Excel files with word-level timestamps |\n| `--kind` | `recall` (default), `story` | Picks the conventional directories: `recall` = `data/4_recall_audio/` → `output/recall_audio-transcribed/`; `story` = `data/1_story_audio/` → `output/story_audio-transcribed/` |\n| `-i, --input` | path | Input audio directory (overrides the `--kind` default) |\n| `-o, --output` | path | Output directory (overrides the `--kind` default) |\n| `--filter` | substring | Only transcribe files whose name matches this item id |\n\nRequires `pip install \"narraters[audio]\"` (or `pip install -e \".[audio]\"` from a clone). Text-only projects can skip Step 1 entirely.\n\n### Step 2 — `segment` (story → events)\n\n```bash\nnarraters segment --method clause\nnarraters segment --method api --model \u003canthropic-model-id\u003e --prompt-version event_segment\nnarraters segment --method fine --input data/2_story_transcript/my_story.txt\n```\nRun `narraters segment --list-models` for the exact `--model` strings (Anthropic, OpenAI, and Ollama-backed presets).\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--method` | `clause`, `fine`, `coarse`, `api` | `clause` needs no model; `fine`/`coarse` use spaCy if installed; `api` calls an LLM |\n| `--model` | see `narraters segment --list-models` | Only used with `--method api` (Anthropic, OpenAI, or Ollama preset keys) |\n| `--prompt-version` | see `--list-prompts` | Selects a template from `scripts/prompt/event_segment*.txt` |\n| `-i, --input` | path | Single transcript file or a directory (else processes all) |\n| `-o, --output` | path | Output directory (default: `data/3_story_events/`) |\n\n### Step 3 — `correct` (spell / grammar fixes)\n\n```bash\nnarraters correct --method rules\nnarraters correct --method gemma-ollama --ollama-model gemma4:e4b\n```\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--method` | `rules`, `gemma-ollama` | `rules` runs entirely locally with no model; `gemma-ollama` needs a local Ollama server |\n| `--ollama-model` | e.g. `gemma4:e4b` | Local Ollama model tag (with `gemma-ollama`) |\n| `--prompt-file` | path | Override the instructions file (default: `scripts/prompt/spell_gram.txt`) |\n| `-i, --input` | path | Single recall text file |\n| `-o, --output` | path | Output directory |\n\nMinimal corrections only — Step 3 fixes spelling/grammar errors and never rewrites or paraphrases.\n\n### Step 4 — `parse` (recall text → clause-level segments)\n\n```bash\nnarraters parse --method rules\nnarraters parse --method ollama --model gemma4:e4b --prompt-version recall_parse_clause\nnarraters parse --filter-pattern sub-02            # process one subject only\n```\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--method` | `rules`, `ollama` | `rules` is the default (regex, no model); `ollama` uses local Gemma |\n| `--model` | e.g. `gemma4:e4b` | Ollama model tag (with `--method ollama`) |\n| `--prompt-version` | see `scripts/prompt/recall_parse_*.txt` | Prompt template name |\n| `-i, --input` | path | Input directory (default: `output/recall_corrected/`) |\n| `-o, --output` | path | Output directory (default: `output/recall_parsed/`) |\n| `--filter-pattern` | substring | Optional filter to process a single subject |\n\n### Step 5 — `match` (recall segments ↔ story events)\n\n```bash\nnarraters match --test-mode                       # simulated keyword matching, no model/API\nnarraters match --method api --story-events data/3_story_events\nnarraters match --method gemma-ollama\nnarraters match --method rmatch                   # embedding matcher (requires [match])\n```\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--method` | `test`, `api`, `gemma-ollama`, `rmatch` | `test` is keyword-based, free, and always available; `rmatch` needs `pip install \"narraters[match]\"` |\n| `--story-events` | path | Directory of `{story}_events.xlsx` (default: `data/3_story_events`) |\n| `-i, --input` | path | Recall-parsed input directory (default: `output/recall_parsed/`) |\n| `-o, --output` | path | Output directory (default: `output/recall_rated/`) |\n| `--test-mode` | flag | Equivalent to `--method test` — simulated matching, no API calls |\n\n### Step 6 — `rate` (causal relationships between event pairs)\n\n```bash\nnarraters rate --method linguistic\nnarraters rate --method api --model \u003canthropic-or-openai-model-id\u003e --prompt-version causal_rating\nnarraters rate --method manual                    # write an empty matrix for hand rating\n```\nUse `narraters rate --help` and the Step 6 model dropdown in the web UI for supported `--model` values when using `--method api`.\n\n| Option | Choices | Notes |\n|---|---|---|\n| `--method` | `linguistic`, `api`, `manual` | `linguistic` is rule-based (no model); `manual` scaffolds an N×N matrix to fill in by hand |\n| `--model` | see web UI / provider docs | Only used with `--method api` |\n| `--prompt-version` | see `scripts/prompt/causal_rating*.txt` | Prompt template name |\n| `-i, --input` | path | Input file/directory |\n| `-o, --output` | path | Output directory |\n\n---\n\n\n\u003c/div\u003e\n\n## Library / Python use\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n```python\nfrom narraters import __version__, project_root\nprint(__version__, project_root())\n```\n\nDirect per-step imports are planned for a future release; for now, programmatic use should call the CLI via `subprocess` or import the modules under `scripts/`.\n\n---\n\n\n\u003c/div\u003e\n\n## Project layout\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nAfter unzipping, everything lives under a single **`narRaters/`** project root. Paths, contents, and naming conventions:\n\n### Folder structure\n\n```text\nnarRaters/\n├── README.md                    # This file — user guide \u0026 pipeline docs\n├── CONTRIBUTING.md              # Research background, prompt templates, acknowledgements, author\n├── LICENSE\n├── narRater_Tutorial.pdf        # Illustrated web UI tour\n├── narRater.app                 # macOS double-click launcher\n├── narRaters_installer.bat      # Windows launcher\n├── install.sh                   # macOS / Linux installer\n├── pyproject.toml               # Package metadata \u0026 pip extras\n├── SETUP_API.md, .env.example   # API key setup\n│\n├── data/                        # Inputs (see Where to put your data)\n│   ├── 1_story_audio/           # Optional Step 1 — story audio\n│   │   └── {story}.wav | .mp3 | .m4a\n│   ├── 2_story_transcript/      # Story text\n│   │   └── {story}.txt          # plain UTF-8, one story per file\n│   ├── 3_story_events/          # Pre-segmented or segmented story events\n│   │   └── {story}_events.xlsx  # columns: event, story_texts\n│   ├── 4_recall_audio/          # Optional Step 1 — recall audio\n│   │   └── {subj_id}.wav | .mp3 | .m4a | .mp4\n│   └── 5_recall_texts/          # Recall text\n│       └── {subj_id}.txt        # e.g. the_siren_sub-01.txt\n│\n├── output/                      # Pipeline outputs (one subfolder per step)\n│   ├── story_audio-transcribed/ # Step 1 (story) — {story}.txt\n│   ├── recall_audio-transcribed/# Step 1 (recall) — {subj_id}.txt\n│   ├── recall_corrected/        # Step 3 — {subj_id}.txt\n│   ├── recall_parsed/           # Step 4 — {subj_id}_parsed.xlsx\n│   ├── recall_rated/            # Step 5 — {subj_id}_{method}.xlsx\n│   └── causal_rated/            # Step 6 — {story}_causal-{method}.xlsx\n│\n├── scripts/                     # Pipeline backends (CLI \u0026 web UI call these)\n│   ├── 1_audio-transcribe.py    # audioTranscribe\n│   ├── 2_story-event-segment.py # eventSegment\n│   ├── 3_spell-grammar-correct.py # sentenceCorrect\n│   ├── 4_parse-texts.py         # textParsing\n│   ├── 5_recall-rater.py        # textMatching\n│   ├── 6_causal-rater.py        # causalRating\n│   └── prompt/                  # LLM prompt templates (.txt)\n│       ├── event_segment.txt\n│       ├── spell_gram.txt\n│       ├── recall_parse_clause.txt\n│       ├── recall_rating.txt\n│       └── causal_rating.txt\n│\n├── server/                      # Flask web UI\n│   ├── web-interface.py         # Routes \u0026 subprocess orchestration\n│   └── START_HERE.command       # macOS launcher script\n│\n├── templates/                   # Web UI HTML (pipeline, dashboard, subject/story)\n├── static/                      # CSS, JS, app icon\n│\n├── src/narraters/               # pip package\n│   ├── cli.py                   # narraters command entry point\n│   ├── paths.py                 # Project-root resolution\n│   └── runtime_install.py       # Bundled-example copy on first serve\n│\n├── helpers/                     # Shared utilities \u0026 smoke tests\n│   ├── software_paths.py        # Canonical path resolution\n│   ├── step_files.py            # Flexible step input/output file recognition\n│   ├── resource_preflight.py    # RAM / disk checks for heavy methods\n│   └── test_*.py                # Pipeline validation scripts\n│\n├── docs/                        # GitHub Pages site \u0026 README assets\n│   ├── index.html               # Project landing page\n│   └── screenshots/             # README GIFs (+ recall-matching.png for site og:image)\n│\n├── demo/                        # Smaller lighthouse example\n│   ├── data/                    # the_lighthouse transcript + recall texts\n│   └── output/                  # Sample outputs for the demo story\n│\n├── developer/                   # Contributor handbook \u0026 tooling\n│   ├── README.md                # Per-step I/O contracts \u0026 design principles\n│   └── SETUP_API.md             # API key setup (developer copy)\n│\n└── packaging/macos/             # App bundle / DMG build scripts\n    └── build_app_bundle.sh\n```\n\nBundled examples: **`pieman_edited`**, **`the_siren`** — see [Example input/output data](#example-inputoutput-data).\n\n**Versioning:** automated files use `{id}_{method}.ext`; hand-edited exports use `{id}_{ratername}-edit.ext` (never overwritten).\n\n---\n\n\n\u003c/div\u003e\n\n## Further reading\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n- **[Project home (GitHub Pages)](https://xianneuro.github.io/narRaters/)** — landing page for search and sharing.\n- **[`narRater_Tutorial.pdf`](narRater_Tutorial.pdf)** — illustrated, click-by-click tour of the web UI; good next step after [Installation](#installation).\n- **[`SETUP_API.md`](SETUP_API.md)** — API keys for Anthropic, OpenAI, and Hugging Face; which pipeline steps need which.\n- **[`scripts/prompt/README.md`](scripts/prompt/README.md)** — prompt template conventions for LLM-backed methods.\n\n---\n\n\n\u003c/div\u003e\n\n## Citation\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nIf you use narRaters in research, please cite the archived release.\n\n**Reference list (APA 7):**\n\n\u003e Li, X. (2026). *narRaters: Naturalistic narratives processing platform* (Version 0.3.14) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20486080\n\nReplace the version number with the release you used (see [Zenodo](https://doi.org/10.5281/zenodo.20486080) for the latest).\n\n**Examples in a manuscript:**\n\n*Methods — in-text:*\n\u003e Narrative recall data were processed with narRaters (Li, 2026).\n\n*Methods — first mention (optional):*\n\u003e We used narRaters (Li, 2026), an open-source pipeline for transcribing, segmenting, parsing, matching, and rating narrative recall data, with human review at each step.\n\n*Software / code availability:*\n\u003e narRaters (Version 0.3.14) is available at https://doi.org/10.5281/zenodo.20486080.\n\n*Data processing statement:*\n\u003e Story events, parsed recall clauses, recall-to-event matches, and causal ratings were produced with narRaters (Li, 2026; https://doi.org/10.5281/zenodo.20486080).\n\n---\n\n\n\u003c/div\u003e\n\n## Acknowledgements\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n- **Janice Chen** for brainstorming the causal-rating step interface and for help testing and improving package functionality.\n- **Gabi Kressin Palacios** and **Dhruva Arekar** for an additional method for the recall-matching step (matching human recall text to story events). See [GabrielKP/rMatch](https://github.com/GabrielKP/rMatch) for human-data–validated AI-assisted recall rating.\n- **Xiyu Li (Rita)** for contributions to the `recall_rating` prompt development and for validating model performance on human recall data (commercial LLM APIs were close to human raters).\n- **Sebastian Michelmann** for feedback on the event-segmentation step (see [Michelmann et al., 2023](https://arxiv.org/abs/2301.10297)).\n- **Colette Youstra** and **[Quinton Covington](https://qcovington.com)** for testing the app's manual-rating functions.\n- **Samira Tavassoli** and **Yuye Huang** for help testing the app's segmentation and causal-reasoning functions.\n\n---\n\n\n\u003c/div\u003e\n\n## Author\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\n**[Xian Li](https://www.xian-li.com)** — [xianl.cogneuro@gmail.com](mailto:xianl.cogneuro@gmail.com)\n\n---\n\n\n\u003c/div\u003e\n\n## License\n\n\u003cdiv style=\"padding-left: 0.5em\"\u003e\n\nSee **[LICENSE](LICENSE)** — **narRaters Research and Non-Commercial License**. Free for research, education, and other non-commercial use; commercial or for-profit use requires prior written permission. Contact [xianl.cogneuro@gmail.com](mailto:xianl.cogneuro@gmail.com) for commercial licensing.\n\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxianneuro%2Fnarraters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxianneuro%2Fnarraters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxianneuro%2Fnarraters/lists"}