{"id":17298295,"url":"https://github.com/chanind/frame-semantic-transformer","last_synced_at":"2025-04-14T11:11:02.826Z","repository":{"id":37276697,"uuid":"487276692","full_name":"chanind/frame-semantic-transformer","owner":"chanind","description":"Frame Semantic Parser based on T5 and FrameNet","archived":false,"fork":false,"pushed_at":"2023-09-13T14:00:34.000Z","size":1088,"stargazers_count":54,"open_issues_count":9,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-01T03:53:08.577Z","etag":null,"topics":["framenet","huggingface","nlp","semantic-parsing","t5","transformers"],"latest_commit_sha":null,"homepage":"https://chanind.github.io/frame-semantic-transformer","language":"Python","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/chanind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-30T12:52:35.000Z","updated_at":"2024-10-24T05:46:48.000Z","dependencies_parsed_at":"2023-01-29T15:30:51.143Z","dependency_job_id":null,"html_url":"https://github.com/chanind/frame-semantic-transformer","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanind%2Fframe-semantic-transformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanind%2Fframe-semantic-transformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanind%2Fframe-semantic-transformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanind%2Fframe-semantic-transformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chanind","download_url":"https://codeload.github.com/chanind/frame-semantic-transformer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223629045,"owners_count":17176061,"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":["framenet","huggingface","nlp","semantic-parsing","t5","transformers"],"created_at":"2024-10-15T11:18:41.514Z","updated_at":"2024-11-08T04:02:25.492Z","avatar_url":"https://github.com/chanind.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Frame Semantic Transformer\n\n[![ci](https://img.shields.io/github/actions/workflow/status/chanind/frame-semantic-transformer/ci.yaml?branch=main)](https://github.com/chanind/frame-semantic-transformer)\n[![PyPI](https://img.shields.io/pypi/v/frame-semantic-transformer?color=blue)](https://pypi.org/project/frame-semantic-transformer/)\n\nFrame-based semantic parsing library trained on [FrameNet](https://framenet2.icsi.berkeley.edu/) and built on HuggingFace's [T5 Transformer](https://huggingface.co/docs/transformers/model_doc/t5)\n\n**Live Demo: [chanind.github.io/frame-semantic-transformer](https://chanind.github.io/frame-semantic-transformer)**\n\nFull docs: [frame-semantic-transformer.readthedocs.io](https://frame-semantic-transformer.readthedocs.io/)\n\n## About\n\nThis library draws heavily on [Open-Sesame](https://github.com/swabhs/open-sesame) ([paper](https://arxiv.org/abs/1706.09528)) for inspiration on training and evaluation on FrameNet 1.7, and uses ideas from the paper [Open-Domain Frame Semantic Parsing Using Transformers](https://arxiv.org/abs/2010.10998) for using T5 as a frame-semantic parser. [SimpleT5](https://github.com/Shivanandroy/simpleT5) was also used as a base for the initial training setup.\n\nMore details: [FrameNet Parsing with Transformers Blog Post](https://chanind.github.io/ai/2022/05/24/framenet-transformers.html)\n\n## Performance\n\nThis library uses the same train/dev/test documents and evaluation methodology as Open-Sesame, so that the results should be comparable between the 2 libraries. There are 2 pretrained models available, `base` and `small`, corresponding to `t5-base` and `t5-small` in Huggingface, respectively.\n\n| Task                   | Sesame F1 (dev/test) | Small Model F1 (dev/test) | Base Model F1 (dev/test) |\n| ---------------------- | -------------------- | ------------------------- | ------------------------ |\n| Trigger identification | 0.80 / 0.73          | 0.75 / 0.71               | 0.78 / 0.74              |\n| Frame classification   | 0.90 / 0.87          | 0.87 / 0.86               | 0.91 / 0.89              |\n| Argument extraction    | 0.61 / 0.61          | 0.76 / 0.73               | 0.78 / 0.75              |\n\nThe base model performs similarly to Open-Sesame on trigger identification and frame classification tasks, but outperforms it by a significant margin on argument extraction. The small pretrained model has lower F1 than base across the board, but is 1/4 the size and still outperforms Open-Sesame at argument extraction.\n\n## Installation\n\n```\npip install frame-semantic-transformer\n```\n\n## Usage\n\n### Inference\n\nThe main entry to interacting with the library is the `FrameSemanticTransformer` class, as shown below. For inference the `detect_frames()` method is likely all that is needed to perform frame parsing.\n\n```python\nfrom frame_semantic_transformer import FrameSemanticTransformer\n\nframe_transformer = FrameSemanticTransformer()\n\nresult = frame_transformer.detect_frames(\"The hallway smelt of boiled cabbage and old rag mats.\")\n\nprint(f\"Results found in: {result.sentence}\")\nfor frame in result.frames:\n    print(f\"FRAME: {frame.name}\")\n    for element in frame.frame_elements:\n        print(f\"{element.name}: {element.text}\")\n```\n\nThe result returned from `detect_frames()` is an object containing `sentence`, a parsed version of the original sentence text, `trigger_locations`, the indices within the sentence where frame triggers were detected, and `frames`, a list of all detected frames in the sentence. Within `frames`, each object containes `name` which corresponds to the FrameNet name of the frame, `trigger_location` corresponding to which trigger in the text this frame this frame uses, and `frame_elements` containing a list of all relevant frame elements found in the text.\n\nFor more efficient bulk processing of text, there's a `detect_frames_bulk` method which will process a list of sentences in batches. You can control the batch size using the `batch_size` param. By default this is `8`.\n\n```python\nframe_transformer = FrameSemanticTransformer(batch_size=16)\n\nresult = frame_transformer.detect_frames_bulk([\n    \"I'm getting quite hungry, but I can wait a bit longer.\",\n    \"The chef gave the food to the customer.\",\n    \"The hallway smelt of boiled cabbage and old rag mats.\",\n])\n```\n\n**Note**: It's not recommended to pass more than a single sentence per string to `detect_frames()` or `detect_frames_bulk()`. If you have a paragraph of text to process, it's best to split the paragraph into a list of sentences and pass the sentences as a list to `detect_frames_bulk()`. Only single sentences per string were used during training, so it's not clear how the model will handle multiple sentences in the same string.\n\n```python\n# ❌ Bad, don't do this\nframe_transformer.detect_frames(\"Fuzzy Wuzzy was a bear. Fuzzy Wuzzy had no hair.\")\n\n# 👍 Do this instead\nframe_transformer.detect_frames_bulk([\n  \"Fuzzy Wuzzy was a bear.\",\n  \"Fuzzy Wuzzy had no hair.\",\n])\n```\n\n### Running on GPU vs CPU\n\nBy default, `FrameSemanticTransformer` will attempt to use a GPU if one is available. If you'd like to explictly set whether to run on GPU vs CPU, you can pass the `use_gpu` param.\n\n```python\n# force the model to run on the CPU\nframe_transformer = FrameSemanticTransformer(use_gpu=False)\n```\n\n### Loading Models\n\nThere are currently 2 available pre-trained models for inference, called `base` and `small`, fine-tuned from HuggingFace's [t5-base](https://huggingface.co/t5-base) and [t5-small](https://huggingface.co/t5-small) model respectively. If a local fine-tuned t5 model exists that can be loaded as well. If no model is specified, the `base` model will be used.\n\n```\nbase_transformer = FrameSemanticTransformer(\"base\") # this is also the default\nsmall_transformer = FrameSemanticTransformer(\"small\") # a smaller pretrained model which is faster to run\ncustom_transformer = FrameSemanticTransformer(\"/path/to/model\") # load a custom t5 model\n```\n\nBy default, models are lazily loaded when `detect_frames()` is first called. If you want to load the model sooner, you can call `setup()` on a `FrameSemanticTransformer` instance to load models immediately.\n\n```\nframe_transformer = FrameSemanticTransformer()\nframe_transformer.setup() # load models immediately\n```\n\n## Contributing\n\nAny contributions to improve this project are welcome! Please open an issue or pull request in this repo with any bugfixes / changes / improvements you have!\n\nThis project uses [Black](https://github.com/psf/black) for code formatting, [Flake8](https://flake8.pycqa.org/en/latest/) for linting, and [Pytest](https://docs.pytest.org/) for tests. Make sure any changes you submit pass these code checks in your PR. If you have trouble getting these to run feel free to open a pull-request regardless and we can discuss further in the PR.\n\n## License\n\nThe code contained in this repo is released under a MIT license, however the pretrained models are released under an Apache 2.0 license in accordance with FrameNet training data and HuggingFace's T5 base models.\n\n## Citation\n\nIf you use Frame semantic transformer in your work, please cite the following:\n\n```bibtex\n@article{chanin2023opensource,\n  title={Open-source Frame Semantic Parsing},\n  author={Chanin, David},\n  journal={arXiv preprint arXiv:2303.12788},\n  year={2023}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanind%2Fframe-semantic-transformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanind%2Fframe-semantic-transformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanind%2Fframe-semantic-transformer/lists"}