{"id":23734029,"url":"https://github.com/trialandsuccess/verysimpletransformers","last_synced_at":"2025-09-04T09:33:21.866Z","repository":{"id":196194682,"uuid":"693279196","full_name":"trialandsuccess/verysimpletransformers","owner":"trialandsuccess","description":"Very Simple Transformers provides a simplified interface for packaging, deploying, and serving Transformer models.","archived":false,"fork":false,"pushed_at":"2023-11-17T11:11:20.000Z","size":126,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-16T01:50:53.825Z","etag":null,"topics":["huggingface","machine-learning","python","simpletransformers","transformers","vst"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/verysimpletransformers","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trialandsuccess.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-09-18T17:52:13.000Z","updated_at":"2024-10-13T06:01:31.000Z","dependencies_parsed_at":"2023-11-15T14:27:09.575Z","dependency_job_id":"1c0420a3-afcf-46d9-bcdc-39cad2ad2479","html_url":"https://github.com/trialandsuccess/verysimpletransformers","commit_stats":null,"previous_names":["trialandsuccess/verysimpletransformers"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/trialandsuccess/verysimpletransformers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trialandsuccess%2Fverysimpletransformers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trialandsuccess%2Fverysimpletransformers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trialandsuccess%2Fverysimpletransformers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trialandsuccess%2Fverysimpletransformers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trialandsuccess","download_url":"https://codeload.github.com/trialandsuccess/verysimpletransformers/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trialandsuccess%2Fverysimpletransformers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273583392,"owners_count":25131812,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"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":["huggingface","machine-learning","python","simpletransformers","transformers","vst"],"created_at":"2024-12-31T05:33:28.681Z","updated_at":"2025-09-04T09:33:21.564Z","avatar_url":"https://github.com/trialandsuccess.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Very Simple Transformers (VST)\n\n\u003cdiv align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/verysimpletransformers\"\u003e\u003cimg alt=\"PyPI - Version\" src=\"https://img.shields.io/pypi/v/verysimpletransformers.svg\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/verysimpletransformers\"\u003e\u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/verysimpletransformers.svg\"/\u003e\u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-yellow.svg\"/\u003e\u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://github.com/trialandsuccess/verysimpletransformers/actions\"\u003e\n        \u003cimg alt=\"verysimpletransformers checks\" src=\"https://github.com/trialandsuccess/verysimpletransformers/actions/workflows/su6.yml/badge.svg?branch=master\"/\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/trialandsuccess/verysimpletransformers/actions\"\u003e\u003cimg alt=\"Coverage\" src=\"https://raw.githubusercontent.com/trialandsuccess/verysimpletransformers/master/coverage.svg\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n-----\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [CLI](#cli)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Installation\n\n## Usage\n\n### Bundling\n\nBundling your machine learning model with VerySimpleTransformers is straightforward. Follow these steps:\n\nCreate or load your machine learning model (e.g., a ClassificationModel) using Simple Transformers.\n\nExample:\n\n```python\nfrom simpletransformers.classification import ClassificationArgs, ClassificationModel\n\n# Create a ClassificationModel\nmodel_args = ClassificationArgs(\n    num_train_epochs=1,\n    overwrite_output_dir=True,\n    save_model_every_epoch=False,\n)\n\nmodel = ClassificationModel(\n    \"bert\",\n    \"bert-base-cased\",  # or something like ./outputs\n    args=model_args,\n    use_cuda=True,\n)\n# optionally train on your data:\nmodel.train_model(...)\n\n```\n\nImport the `verysimpletransformers` package, and use the `to_vst` function to package the model into a .vst file with\noptional compression.\n\nProvide the model, the output file path, and an optional compression level (0-9).\nBy default, compression will be disabled.\n\nThe output file path can be specified as:\n\n- A string path (e.g., `\"model.vst\"`) for a standard file path.\n- A `Path` object (e.g., `Path(\"model.vst\")`) using `pathlib`.\n- A binary I/O object (e.g., `BytesIO()`) for in-memory operations, if you don't want to save to a file.\n\nExample:\n\n```python\nimport verysimpletransformers  # or: from verysimpletransformers import to_vst\nfrom pathlib import Path  # can be used instead of a string\n\nverysimpletransformers.to_vst(model,\n                              \"my_model.vst\",\n                              compression=5,  # optional\n                              )\n```\n\nNote: As an alias, `bundle_model` can be used instead of `to_vst`.\n\n### Loading\n\nLoading a machine learning model from a .vst file is just as simple. Follow these steps:\n\nImport `from_vst` from `simpletransformers`.\nSpecify the path to the .vst file you want to load. Just like with `to_vst`, this path can be a `str`, `Path` or binary\nIO.\nUse the `from_vst` function to load the model. Optionally, you can specify the `device` parameter to set the device (\ne.g., 'cpu' or 'cuda'). If not specified, the function will select a device based on availability.\n\nExample:\n\n```python\nfrom verysimpletransformers import from_vst\nfrom pathlib import Path\n\nfp = Path(\"model.vst\")  # can also be simply a string.\n\nnew_model = from_vst(fp,\n                     device='cuda',  # optional\n                     )\n\n```\n\nYou can now use the `new_model` for various machine learning tasks.\n\nNote: As an alias, `load_model` can be used instead of `to_vst`.\n\n#### Additional Information\n\n- The `.vst` files can be transferred and used across different devices, regardless of where the model was originally\n  trained.\n\n- Ensure that you have the required dependencies, such as SimpleTransformers and PyTorch, installed to use these\n  functions effectively.\n\n### Full Example\n\nTo see a full example of saving and loading a `.vst` file,\nsee [examples/basic.py](https://github.com/trialandsuccess/verysimpletransformers/tree/master/examples/basic.py)\n\n## CLI\n\nThe VerySimpleTransformers CLI provides a convenient and versatile way to interact with and manage your machine learning\nmodels created with VerySimpleTransformers. It allows you to perform various actions using a command-line interface,\nmaking it easy to run, serve, and upgrade your models with ease.\n\n### Usage\n\nYou can use the CLI with either `verysimpletransformers` or `vst` interchangeably. Here are some basic usage examples:\n\n- Running a model interactively:\n  ```shell\n  verysimpletransformers model.vst\n  vst model.vst\n  ./model.vst\n  ```\n\n- Specifying an action when running:\n  ```shell\n  verysimpletransformers \u003caction\u003e model.vst\n  verysimpletransformers model.vst \u003caction\u003e\n  vst \u003caction\u003e model.vst\n  vst model.vst \u003caction\u003e\n  ./model.vst \u003caction\u003e # if the file has execution rights\n  ```\n\n### Available Actions\n\nThe following actions are available:\n\n- **'run'**: Run the model interactively by typing prompts.\n\n- **'serve'**: Start a simple HTTP server to serve model outputs. You can specify the following options:\n    - `--port \u003cPORT\u003e`: Specify the port number (default: 8000).\n    - `--host \u003cHOST\u003e`: Specify the host (default: 'localhost').\n\n- **'upgrade'**: Upgrade the metadata of a model to the latest version.\n\n### Example\n\nHere's an example of starting a server for a classification model:\n\n```shell\nvst serve ./classification.vst\n./classification.vst serve \n```\n\nFor more examples,\nsee [examples/basic.sh](https://github.com/trialandsuccess/verysimpletransformers/tree/master/examples/basic.sh)\n\n### Notes\n\n- A .vst file (e.g., 'model.vst') is required for most commands.\n- You can specify `\u003caction\u003e`, which can be one of the available options mentioned above.\n- If you leave `\u003caction\u003e` empty, a dropdown menu will appear for you to select from.\n- You can use 'vst' or 'verysimpletransformers' interchangeably.\n\n## About the .vst file format\n\nThe `.vst` file format is used to bundle machine learning models created with SimpleTransformers. Understanding its\nstructure is useful for working with these files effectively. The format consists of the following components:\n\n- **Shebang Line**: The first line of the file is a shebang (`#!/usr/bin/env verysimpletransformers`) that allows the\n  file to be executed using `./`. This line indicates that the file can be executed as a script.\n\n- **Fixed Information (16 bytes)**:\n    - `VST Protocol Version` (short, 2 bytes): Specifies the version of the VerySimpleTransformers Protocol used in the\n      file. This allows for backwards compatibility with older versions of the file, which may have less metadata.\n    - `Metadata Length` (short, 2 bytes): Indicates the length of the metadata section in bytes.\n    - `Content Length` (long long, 8 bytes): Specifies the length of the content (actual model data) in bytes.\n\n  **Explanation**: The total size of the fixed information is 12 bytes according to the data types (2 bytes\n  for `short` + 2 bytes for `short` + 8 bytes for `long long`). However, it sums up to 16 bytes due to `struct` padding.\n  The padding aligns the data structure to meet memory alignment requirements and ensure efficient memory access.\n\n- **Metadata (Variable Length)**:\n    - The next `Metadata Length` bytes contain the metadata, which can vary in length. The metadata is used to store\n      information about the model and its compatibility with different versions of VerySimpleTransformers. The structure\n      of the metadata can change between protocol versions.\n\n    - Checks are performed on this metadata to ensure compatibility and integrity. If the metadata is invalid or belongs\n      to a newer protocol version, a warning is issued, and the loading process continues.\n\n- **Model Content (Variable Length)**:\n    - The remaining bytes, equal to `Content Length`, contain the serialized model data. This is the actual (possibly\n      compressed) machine learning model that was bundled into the `.vst` file.\n    - The model contents are stored (and loaded) using `dill` (which is an extension of `pickle`).\n\n```\n\n\n                              ┌───────────────────────────────────────┐\n                              │#!/usr/bin/env verysimpletransformers\\n├──────────► Shebang\n                              ├───┬───┬───────────┬───────────────────┤\n                              │   │   │           │                   │\n                              │2b │2b │  4 bytes  │  content length   │\n              .vst version  ◄─┼── │   │           │       (n2)        ├──────────► 16 bytes\n                              │   │   │ (padding) │                   │\n    meta header length (n1) ◄─┼───┼── │           │      8 bytes      │\n                              │   │   │           │                   │\n                              ├───┴───┴───────────┴───────────────────┤\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │              Meta Header              │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                n1 bytes               │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              ├───────────────────────────────────────┤\n                              │                                       │\n                              │                                       │\n                              │         (possible compressed)         │\n                              │                                       │\n                              │                                       │\n                              │      Machine Learning Model Dill      │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │               n2 bytes                │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │                                       │\n                              │            ..............             │\n                              │                                       │\n                              └───────────────────────────────────────┘\n\n\n```\n\n### Converting a `vst` file back into the original model files\n\nIf you want to retrieve the original model files from a saved vst file, you can use the `dump_to_disk()` function:\n\n```python\nfrom verysimpletransformers import dump_to_disk\n\nvst_path = 'my_model.vst'\n\n# Convert vst file to original model files\ndump_to_disk(vst_path,  # a running model or path to a .vst file\n             'model_files/',  # optional, default is 'outputs/'\n             )\n```\n\nThis will extract the model contents from the vst file and save the individual components in the `model_files/`\ndirectory:\n\n- `pytorch_model.bin` - Model weights\n- `tokenizer.json` - Tokenizer configuration\n- `vocab.txt` - Vocabulary\n- etc.\n\nThis allows you to easily retrieve the original model files from a vst save file in order to upload or share the model\nto e.g. huggingface.\n\n## Extra's\n\n### Drive\n\nTo enable integration with Google Drive, this extra uses the\nlibrary [drive-in](https://github.com/robinvandernoord/drive-in) to enable uploading and downloading models from Drive.\n\n```bash\npip install verysimpletransformers[drive]\n```\n\n```python\nfrom verysimpletransformers.drive import to_drive, from_drive\n\nmodel: ClassificationModel  # or some other model\n\ndrive_url = to_drive(model)\n# ...\n\nnew_model: ClassificationModel = from_drive(drive_url)\n```\n\n**Limitations:**\n\n- Due to limitations with oauth2 (without using a private key, which is not feasible for an open source project),\n  you can only access files created by this app (i.e. uploaded with `to_drive`).\n- By default, you're redirected to https://oauth.trialandsuccess.nl/callback after authenticating your Google account.\n  This page runs [oauth-echoer](https://github.com/trialandsuccess/oauth-echoer) and simply returns the access token\n  from the query arguments.\n  If you want to change this endpoint, you can pass a `client_id` and `redirect_uri` to the Drive functions.\n  Doing so requires an oauth app with `drive.file` permissions.\n\n## License\n\n`verysimpletransformers` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n## Changelog\n\nSee `CHANGELOG.md` [on GitHub](https://github.com/trialandsuccess/verysimpletransformers/blob/master/CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrialandsuccess%2Fverysimpletransformers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrialandsuccess%2Fverysimpletransformers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrialandsuccess%2Fverysimpletransformers/lists"}