{"id":13688901,"url":"https://github.com/allenai/tango","last_synced_at":"2025-06-15T00:08:26.282Z","repository":{"id":37787398,"uuid":"409415680","full_name":"allenai/tango","owner":"allenai","description":"Organize your experiments into discrete steps that can be cached and reused throughout the lifetime of your research project.","archived":false,"fork":false,"pushed_at":"2024-05-30T21:08:02.000Z","size":2288,"stargazers_count":562,"open_issues_count":71,"forks_count":51,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-13T18:16:46.337Z","etag":null,"topics":["ai","machine-learning","nlp","python","python3","pytorch"],"latest_commit_sha":null,"homepage":"https://ai2-tango.readthedocs.io/","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/allenai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","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}},"created_at":"2021-09-23T02:03:57.000Z","updated_at":"2025-06-03T14:37:27.000Z","dependencies_parsed_at":"2023-10-14T21:15:32.476Z","dependency_job_id":"e2d46a4f-404f-4b26-bf73-11c855e10ca8","html_url":"https://github.com/allenai/tango","commit_stats":{"total_commits":846,"total_committers":20,"mean_commits":42.3,"dds":0.5886524822695036,"last_synced_commit":"1ee2c56a0f557de3b2ba0bb25432487f0c4c50b5"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":"allenai/python-package-template","purl":"pkg:github/allenai/tango","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenai%2Ftango","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenai%2Ftango/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenai%2Ftango/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenai%2Ftango/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allenai","download_url":"https://codeload.github.com/allenai/tango/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenai%2Ftango/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259901379,"owners_count":22929224,"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":["ai","machine-learning","nlp","python","python3","pytorch"],"created_at":"2024-08-02T15:01:27.050Z","updated_at":"2025-06-15T00:08:26.257Z","avatar_url":"https://github.com/allenai.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/allenai/tango/main/docs/source/_static/tango_final_horizontal.png\" width=\"600\"/\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cp\u003e\n\u003c!-- start tagline --\u003e\nAI2 Tango replaces messy directories and spreadsheets full of file versions by organizing experiments into discrete steps that can be cached and reused throughout the lifetime of a research project.\n\u003c!-- end tagline --\u003e\n\u003c/p\u003e\n\u003chr/\u003e\n\u003ca href=\"https://github.com/allenai/tango/actions\"\u003e\n    \u003cimg alt=\"CI\" src=\"https://github.com/allenai/tango/workflows/CI/badge.svg?event=push\u0026branch=main\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/ai2-tango/\"\u003e\n    \u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/ai2-tango\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://ai2-tango.readthedocs.io/en/latest/?badge=latest\"\u003e\n    \u003cimg src=\"https://readthedocs.org/projects/ai2-tango/badge/?version=latest\" alt=\"Documentation Status\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/allenai/tango/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/allenai/tango.svg?color=blue\u0026cachedrop\"\u003e\n\u003c/a\u003e\n\u003cbr/\u003e\n\u003c/div\u003e\n\n## Quick links\n\n- [Documentation](https://ai2-tango.readthedocs.io/)\n- [PyPI Package](https://pypi.org/project/ai2-tango/)\n- [Contributing](https://github.com/allenai/tango/blob/main/CONTRIBUTING.md)\n- [License](https://github.com/allenai/tango/blob/main/LICENSE)\n\n## In this README\n\n- [Quick start](#quick-start)\n- [Installation](#installation)\n  - [Installing with PIP](#installing-with-pip)\n  - [Installing with Conda](#installing-with-conda)\n  - [Installing from source](#installing-from-source)\n  - [Checking your installation](#checking-your-installation)\n  - [Docker image](#docker-image)\n- [FAQ](#faq)\n- [Team](#team)\n- [License](#license)\n\n## Quick start\n\nCreate a Tango step:\n\n```python\n# hello.py\n\nfrom tango import step\n\n@step()\ndef hello(name: str) -\u003e str:\n    message = f\"Hello, {name}!\"\n    print(message)\n    return message\n```\n\nAnd create a corresponding experiment configuration file:\n\n```jsonnet\n// hello.jsonnet\n\n{\n  steps: {\n    hello: {\n      type: \"hello\",\n      name: \"World\",\n    }\n  }\n}\n```\n\nThen run the experiment using a local workspace to cache the result:\n\n```bash\ntango run hello.jsonnet -w /tmp/workspace\n```\n\nYou'll see something like this in the output:\n\n```\nStarting new run expert-llama\n● Starting step \"hello\"...\nHello, World!\n✓ Finished step \"hello\"\n✓ Finished run expert-llama\n```\n\nIf you run this a second time the output will now look like this:\n\n```\nStarting new run open-crab\n✓ Found output for step \"hello\" in cache...\n✓ Finished run open-crab\n```\n\nYou won't see \"Hello, World!\" this time because the result of the step was found in the cache, so it wasn't run again.\n\nFor a more detailed introduction check out the [First Steps](https://ai2-tango.readthedocs.io/en/latest/first_steps.html) walk-through.\n\n## Installation\n\n\u003c!-- start install --\u003e\n\n**ai2-tango** requires Python 3.8 or later.\n\n### Installing with `pip`\n\n**ai2-tango** is available [on PyPI](https://pypi.org/project/ai2-tango/). Just run\n\n```bash\npip install ai2-tango\n```\n\nTo install with a specific integration, such as `torch` for example, run\n\n```bash\npip install 'ai2-tango[torch]'\n```\n\nTo install with all integrations, run\n\n```bash\npip install 'ai2-tango[all]'\n```\n\n### Installing with `conda`\n\n**ai2-tango** is available on conda-forge. You can install just the base package with\n\n```bash\nconda install tango -c conda-forge\n```\n\nYou can pick and choose from the integrations with one of these:\n\n```bash\nconda install tango-datasets -c conda-forge\nconda install tango-torch -c conda-forge\nconda install tango-wandb -c conda-forge\n```\n\nYou can also install everything:\n\n```bash\nconda install tango-all -c conda-forge\n```\n\nEven though **ai2-tango** itself is quite small, installing everything will pull in a lot of dependencies.\nDon't be surprised if this takes a while!\n\n### Installing from source\n\nTo install **ai2-tango** from source, first clone [the repository](https://github.com/allenai/tango):\n\n```bash\ngit clone https://github.com/allenai/tango.git\ncd tango\n```\n\nThen run\n\n```bash\npip install -e '.[all]'\n```\n\nTo install with only a specific integration, such as `torch` for example, run\n\n```bash\npip install -e '.[torch]'\n```\n\nOr to install just the base tango library, you can run\n\n```bash\npip install -e .\n```\n\n### Checking your installation\n\nRun\n\n```bash\ntango info\n```\n\nto check your installation.\n\n### Docker image\n\nYou can build a Docker image suitable for tango projects by using [the official Dockerfile](https://github.com/allenai/tango/blob/main/Dockerfile) as a starting point for your own Dockerfile, or you can simply use one of our [prebuilt images](https://github.com/allenai/tango/pkgs/container/tango) as a base image in your Dockerfile. For example:\n\n```Dockerfile\n# Start from a prebuilt tango base image.\n# You can choose the right tag from the available options here:\n# https://github.com/allenai/tango/pkgs/container/tango/versions\nFROM ghcr.io/allenai/tango:cuda11.3\n\n# Install your project's additional requirements.\nCOPY requirements.txt .\nRUN /opt/conda/bin/pip install --no-cache-dir -r requirements.txt\n\n# Install source code.\n# This instruction copies EVERYTHING in the current directory (build context),\n# which may not be what you want. Consider using a \".dockerignore\" file to\n# exclude files and directories that you don't want on the image.\nCOPY . .\n```\n\nMake sure to choose the right base image for your use case depending on the version of tango you're using and the CUDA version that your host machine supports.\nYou can see a list of all available image tags [on GitHub](https://github.com/allenai/tango/pkgs/container/tango/versions).\n\n\u003c!-- end install --\u003e\n\n## FAQ\n\n\u003c!-- start faq --\u003e\n\n### Why is the library named Tango?\n\nThe motivation behind this library is that we can make research easier by composing it into well-defined steps.  What happens when you choreograph a number of steps together?  Well, you get a dance.  And since our [team's leader](https://nasmith.github.io/) is part of a tango band, \"AI2 Tango\" was an obvious choice!\n\n### How can I debug my steps through the Tango CLI?\n\nYou can run the `tango` command through [pdb](https://docs.python.org/3/library/pdb.html). For example:\n\n```bash\npython -m pdb -m tango run config.jsonnet\n```\n\n### How is Tango different from [Metaflow](https://metaflow.org), [Airflow](https://airflow.apache.org), or [redun](https://github.com/insitro/redun)?\n\nWe've found that existing DAG execution engines like these tools are great for production workflows but not as well suited for messy, collaborative research projects\nwhere code is changing constantly. AI2 Tango was built *specifically* for these kinds of research projects.\n\n### How does Tango's caching mechanism work?\n\nAI2 Tango caches the results of steps based on the `unique_id` of the step. The `unique_id` is essentially a hash of all of the inputs to the step along with:\n\n1. the step class's fully qualified name, and\n2. the step class's `VERSION` class variable (an arbitrary string).\n\nUnlike other workflow engines like [redun](https://github.com/insitro/redun), Tango does *not* take into account the source code of the class itself (other than its fully qualified name) because we've found that using a hash of the source code bytes is way too sensitive and less transparent for users.\nWhen you change the source code of your step in a meaningful way you can just manually change the `VERSION` class variable to indicate to Tango\nthat the step has been updated.\n\n\u003c!-- end faq --\u003e\n\n## Team\n\n\u003c!-- start team --\u003e\n\n**ai2-tango** is developed and maintained by the AllenNLP team, backed by [the Allen Institute for Artificial Intelligence (AI2)](https://allenai.org/).\nAI2 is a non-profit institute with the mission to contribute to humanity through high-impact AI research and engineering.\nTo learn more about who specifically contributed to this codebase, see [our contributors](https://github.com/allenai/tango/graphs/contributors) page.\n\n\u003c!-- end team --\u003e\n\n## License\n\n\u003c!-- start license --\u003e\n\n**ai2-tango** is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).\nA full copy of the license can be found [on GitHub](https://github.com/allenai/tango/blob/main/LICENSE).\n\n\u003c!-- end license --\u003e\n","funding_links":[],"categories":["Python","Model, Data and Experiment Tracking"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenai%2Ftango","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallenai%2Ftango","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenai%2Ftango/lists"}