{"id":23237030,"url":"https://github.com/nicolay-r/thor-ecac","last_synced_at":"2026-03-09T11:32:27.078Z","repository":{"id":221309260,"uuid":"753808558","full_name":"nicolay-r/THOR-ECAC","owner":"nicolay-r","description":"The official fork of THoR Chain-of-Thought framework, enhanced and adapted for Emotion Cause Analysis (ECAC-2024)","archived":false,"fork":false,"pushed_at":"2025-07-13T21:17:44.000Z","size":5405,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-13T23:30:32.369Z","etag":null,"topics":["chainofthought","colab-notebook","emotion-analysis","emotion-cause-pair-extraction","fine-tuning","flan-t5","framework","llm","notebook-jupyter","reasoning","semeval","semeval-2024","transformers-models"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2404.03361","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicolay-r.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGESET.md","contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2024-02-06T20:38:47.000Z","updated_at":"2025-07-13T21:17:47.000Z","dependencies_parsed_at":"2024-02-17T23:22:02.648Z","dependency_job_id":"bc997da4-09bf-47b4-a35f-f7e5dc9fbee2","html_url":"https://github.com/nicolay-r/THOR-ECAC","commit_stats":null,"previous_names":["nicolay-r/thor-ecac"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nicolay-r/THOR-ECAC","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolay-r%2FTHOR-ECAC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolay-r%2FTHOR-ECAC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolay-r%2FTHOR-ECAC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolay-r%2FTHOR-ECAC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicolay-r","download_url":"https://codeload.github.com/nicolay-r/THOR-ECAC/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolay-r%2FTHOR-ECAC/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30292424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T11:12:22.024Z","status":"ssl_error","status_checked_at":"2026-03-09T11:10:54.577Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["chainofthought","colab-notebook","emotion-analysis","emotion-cause-pair-extraction","fine-tuning","flan-t5","framework","llm","notebook-jupyter","reasoning","semeval","semeval-2024","transformers-models"],"created_at":"2024-12-19T04:13:24.720Z","updated_at":"2026-03-09T11:32:27.059Z","avatar_url":"https://github.com/nicolay-r.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## THOR: Three-hop Reasoning for Emotion Cause Analysis in Context • [![twitter](https://img.shields.io/twitter/url/https/shields.io.svg?style=social)](https://x.com/nicolayr_/status/1803705227108847866)\n\n![](https://img.shields.io/badge/Python-3.10-lightgreen.svg)\n[![arXiv](https://img.shields.io/badge/arXiv-2404.03361-b31b1b.svg)](https://arxiv.org/abs/2404.03361)\n[![twitter](https://img.shields.io/twitter/url/https/shields.io.svg?style=social)](https://x.com/nicolayr_/status/1803705227108847866)\n[![Youtube badge](https://img.shields.io/badge/-Youtube-Cc4c4c?style=flat-square\u0026logo=Youtube\u0026logoColor=white\u0026link=https://twitter.com/nicolayr_)](https://youtu.be/vRVDQa7vfkU)\n\n**The PyTorch reforged and forked version of the official \n[THoR-framework](https://github.com/scofield7419/THOR-ISA),\nenhanced\nand adapted for SemEval-2024 paper \n[nicolay-r at SemEval-2024 Task 3: Using Flan-T5 for Reasoning Emotion Cause in Conversations with Chain-of-Thought on Emotion States](https://arxiv.org/abs/2404.03361)**\n\n\u003cdiv align=\"center\"\u003e\n\n[![](https://markdown-videos-api.jorgenkh.no/youtube/vRVDQa7vfkU)](https://youtu.be/vRVDQa7vfkU)\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### **Latest Updates**   \n\n\u003e **Update February 23 2025:** 🔥 **BATCHING MODE SUPPORT**. See 🌌 [Flan-T5 provider](https://github.com/nicolay-r/nlp-thirdgate/blob/master/llm/transformers_flan_t5.py) for [bulk-chain](https://github.com/nicolay-r/bulk-chain) project. Test [is available here](https://github.com/nicolay-r/bulk-chain/blob/master/test/test_provider_batching.py)\n\n\u003e **Update 06 June 2024:** 🤗 Model and its description / tutorial for usage has been uploaded on `huggingface`: [🤗 nicolay-r/flan-t5-emotion-cause-thor-base](https://huggingface.co/nicolay-r/flan-t5-emotion-cause-thor-base)\n\n\u003c/summary\u003e\n\n\u003e **Update 06 March 2024**: 🔓 `attrdict` represents the main limitation for code launching in `Python 3.10` and hence been switched to `addict` (see [Issue#2](https://github.com/nicolay-r/THOR-ECAC/issues/2)).\n\n\u003e **Update 05 March 2024**: The quick [arXiv paper](https://arxiv.org/abs/2404.03361) breakdowns 🔨 are @ [Twitter/X post](https://twitter.com/nicolayr_/status/1777005686611751415)\n\n\u003e **Update 17 February 2024**: We support `--bf16` mode for launching Flan-T5 with `torch.bfloat16` type; \n\u003e this feature allows launching `xl`-sized model training with just a single NVidia-A100 (40GB)\n\n\u003e **NOTE:** Since the existed fork aimed on a variety non-commercial projects application, \n\u003e this repository represent **a copy** of the originally published code with the folllowing \n\u003e [🔧 enhancements and changes](CHANGESET.md)\n\n\u003e **NOTE:** [List of the changes](CHANGESET.md) from the original THoR\n\n\u003c/details\u003e\n\n## Contents\n* [Overview](#overview)\n* [📙 **Quickstart in GoogleColab**](#quickstart)\n* [Usage](#code)\n  * [Requirement](#requirement)\n  * [Dataset Preparation](#data)\n  * [**Prompts and CoT**](#prompts-and-engines)\n  * [Training / Inferring](#runt5)\n  * [**Submitting Results on Codalab**](#submitting-results-on-codalab)\n* [References](#references)  \n\n## Overview\u003ca name=\"overview\" /\u003e\n\n* **Input:** a conversation containing the speaker and the text of each utterance.\n* **Output:** all emotion-cause pairs, where each pair contains an emotion utterance along with its emotion category and the textual cause span in a specific cause utterance, e.g:\n  * (`U3_Joy`, `U2_“You made up!”`)\n\n\u003e The complete description of the task is [available here](https://nustm.github.io/SemEval-2024_ECAC/).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./figures/task.png\" width=\"450\"/\u003e\n\u003c/p\u003e\n\n\u003e Framework illustration.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./figures/framework.png\" width=\"1000\"/\u003e\n\u003c/p\u003e\n\n## Quickstart\n\n### 🧪 [Quick start with Emotion CoT ![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nicolay-r/THOR-ECAC/blob/master/SemEval_2024_Task_3_FlanT5_Finetuned_Model_Usage.ipynb)\n### 🔥 [Experiments Reproduction ![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/nicolay-r/THOR-ECAC/blob/master/THoR_Finetuning_SemEval2023_t3_1_public.ipynb)\n\nWe provide 🔥 notebook for downloading all the necessary data, followed by launching\nexperiments with `NVidia-V100`/ or `NVidia-A100`.\n\n**Codalab Submission formation**: please [follow this section](#submitting-results-on-codalab).\n\n\n## Usage\u003ca name=\"code\" /\u003e\n\n### Requirement\u003ca name=\"requirement\" /\u003e\n![](https://img.shields.io/badge/Python-3.10-lightgreen.svg)\n\nThis project has been tested under **Python-3.8** and [adapted](https://github.com/nicolay-r/THOR-ECAC/issues/2) for the **Python-3.10**. \n\nUsing `pip`, you can install the necessary dependencies as follows:\n``` bash \npip install -r requirements.txt\n```\n\n### Datasets\u003ca name=\"data\" /\u003e\n\n### 👉 [Compile datasets manually](https://github.com/nicolay-r/SemEval2024-Task3) 👈\n\n**Serialize datasets**: We provide `download_data.py` script \nfor downloading and serialization of the manually compiled datasets \n(`D_state` and `D_cause`).\n\n\n```python\npython download_data.py \\\n  --cause-test \"https://www.dropbox.com/scl/fi/4b2ouqdhgifqy3pmopq08/cause-mult-test.csv?rlkey=tkw0p1e01vezrjbou6v7qh36a\u0026dl=1\" \\\n  --cause-train \"https://www.dropbox.com/scl/fi/0tlkwbe5awcss2qmihglf/cause-mult-train.csv?rlkey=x9on1ogzn5kigx7c32waudi21\u0026dl=1\" \\\n  --cause-valid \"https://www.dropbox.com/scl/fi/8zjng2uyghbkpbfcogj6o/cause-mult-valid.csv?rlkey=91dgg4ly7p23e3id2230lqsoi\u0026dl=1\" \\\n  --state-train \"https://www.dropbox.com/scl/fi/0lokgaeo973wo82ig01hy/state-mult-train.csv?rlkey=tkt1oyo8kwgqs6gp79jn5vbh8\u0026dl=1\" \\\n  --state-valid \"https://www.dropbox.com/scl/fi/eu4yuk8n61izygnfncnbo/state-mult-valid.csv?rlkey=tlg8rac4ofkbl9o4ipq6dtyos\u0026dl=1\"\n```\n\nFor reproduction purposes you may refer to the **[code of this supplementary repository](https://github.com/nicolay-r/SemEval2024-Task3)**. \n\n### LLMs\u003ca name=\"llm\" /\u003e\n\u003ca href=\"https://huggingface.co/docs/transformers/model_doc/flan-t5\" rel=\"nofollow\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Flan-T5-purple\" alt=\"Build Status\"\u003e\n\u003c/a\u003e\n\nUse the **Flan-T5** as the backbone LLM reasoner:\n  * **[google/flan-t5-base](https://huggingface.co/google/flan-t5-base)**\n  * [google/flan-t5-large](https://huggingface.co/google/flan-t5-large)\n  * [google/flan-t5-xl](https://huggingface.co/google/flan-t5-xl)\n  * [google/flan-t5-xxl](https://huggingface.co/google/flan-t5-xxl)\n\n\u003e **NOTE**: We setup `base` reasoner in [config.yaml](https://github.com/nicolay-r/THOR-ECAC/blob/23a2add3d77f251dfca5241153815d76eb4dee6b/config/config.yaml#L4-L5).\nHowever, **it is highly recommended** to choose the largest reasoning model you can afford (`xl` or higher) for fine-tuning.\n\n### Prompts and Engines\n\nWe provide separate engines, and for each engine the source of the prompts in particular:\n* `prompt_state`: \n  [instruction](https://github.com/nicolay-r/THOR-ECAC/blob/39b768cba5a652bc207725d707b5c41dece574ac/main.py#L143) \n  wrapped into the \n  [prompt](https://github.com/nicolay-r/THOR-ECAC/blob/39b768cba5a652bc207725d707b5c41dece574ac/src/utils.py#L9-L14)\n* `prompt_cause`: \n  [instruction](https://github.com/nicolay-r/THOR-ECAC/blob/39b768cba5a652bc207725d707b5c41dece574ac/main.py#L142) \n  wrapped into the \n  [prompt](https://github.com/nicolay-r/THOR-ECAC/blob/39b768cba5a652bc207725d707b5c41dece574ac/src/utils.py#L9-L14)\n* `thor_state`: [Class of the prompts](src/cot_state.py)\n* `thor_cause`: [Class of the prompts](src/cot_cause.py)\n* `thor_cause_rr`: [Class of the prompts](src/cot_cause.py) same as `thor_cause`\n\n### Training and Evaluating with Flan-T5\u003ca name=\"runt5\" /\u003e\n\nUse the [main.py](main.py) script with command-line arguments to run the \n**Flan-T5-based** THOR system. \n\n\n```bash\npython main.py -c \u003cCUDA_INDEX\u003e \\\n    -m \"google/flan-t5-base\" \\\n    -r [prompt|thor_state|thor_cause|thor_cause_rr]  \\ \n    -d [state_se24|cause_se24] \\\n    -lf \"optional/path/to/the/pretrained/state\" \\\n    -es \u003cEPOCH_SIZE\u003e \\\n    -bs \u003cBATCH_SIZE\u003e \\\n    -f \u003cYAML_CONFIG\u003e \n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n### Parameters list\n\u003c/summary\u003e\n\n* `-c`, `--cuda_index`: Index of the GPU to use for computation (default: `0`).\n* `-d`, `--data_name`: Name of the dataset. Choices are `state_se24` or `cause_se24`.\n* `-m`, `--model_path`: Path to the model on hugging face.\n* `-r`, `--reasoning`: Specifies the reasoning mode, with one-step prompt or multi-step thor mode.\n* `-li`, `--load_iter`: load a state on specific index from the same `data_name` resource (default: `-1`, not applicable.)\n* `-lp`, `--load_path`: load a state on specific path.\n* `-p`, `--instruct`: instructive prompt for `prompt` training engine that involves `target` parameter only\"\n* `-es`, `--epoch_size`: amount of training epochs (default: `1`)\n* `-bs`, `--batch_size`: size of the batch (default: `None`)\n* `-lr`, `--bert_lr`: learning rate (default=`2e-4`)\n* `-t`, `--temperature`: temperature (default=gen_config.temperature)\n* `-v`, `--validate`: running under zero-shot mode on `valid` set.\n* `-i`, `--infer_iter`: running inference on `test` dataset to form answers.\n* `-f`, `--config`: Specifies the location of [config.yaml](config/config.yaml) file.\n\nConfigure more parameters in [config.yaml](config/config.yaml) file.\n\n\u003c/details\u003e\n\n## Submitting Results on Codalab\n\n### 📊 [Codalab Competiton Page](https://codalab.lisn.upsaclay.fr/competitions/16141)\n\nAll the service that is not related to the Codalab is a part of \n**another repository** (link below 👇)\n\nOnce results were inferred ([`THOR-cause-rr` results example](data/google_flan-t5-base-thor_cause_rr-output-sample.csv)), \nyou may refer to the following code to form a submission: \n### 👉 [Codalab Service Repository](https://github.com/nicolay-r/SemEval2024-Task3) 👈\n\n## References\n\nThe original THoR project:\n```bibtex\n@inproceedings{FeiAcl23THOR,\n  title={Reasoning Implicit Sentiment with Chain-of-Thought Prompting},\n  author={Hao, Fei and Bobo, Li and Qian, Liu and Lidong, Bing and Fei, Li and Tat-Seng, Chua},\n  booktitle = \"Proceedings of the Annual Meeting of the Association for Computational Linguistics\",\n  pages = \"1171--1182\",\n  year={2023}\n}\n```\n\nYou can cite this work as follows:\n```bibtex\n@article{rusnachenko2024nicolayr,\n  title={nicolay-r at SemEval-2024 Task 3: Using Flan-T5 for Reasoning Emotion Cause in Conversations with Chain-of-Thought on Emotion States},\n  booktitle = \"Proceedings of the Annual Conference of the North American Chapter of the Association for Computational Linguistics\",\n  author={Nicolay Rusnachenko and Huizhi Liang},\n  year= \"2024\",\n  month= jun,\n  address = \"Mexico City, Mexico\",\n  publisher = \"Annual Conference of the North American Chapter of the Association for Computational Linguistics\"\n}\n```\n\n## Acknowledgement\n\nThis code is referred from following projects:\n[CoT](https://arxiv.org/abs/2201.11903); \n[Flan-T5](https://huggingface.co/docs/transformers/model_doc/flan-t5);\n[Transformers](https://github.com/huggingface/transformers),\n\n## License\n\nThe code is released under Apache License 2.0 for Noncommercial use only. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolay-r%2Fthor-ecac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicolay-r%2Fthor-ecac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolay-r%2Fthor-ecac/lists"}