{"id":13472564,"url":"https://github.com/huggingface/text-clustering","last_synced_at":"2025-10-14T15:30:05.414Z","repository":{"id":227327329,"uuid":"742544032","full_name":"huggingface/text-clustering","owner":"huggingface","description":"Easily embed, cluster and semantically label text datasets","archived":false,"fork":false,"pushed_at":"2024-03-28T16:30:36.000Z","size":790,"stargazers_count":577,"open_issues_count":8,"forks_count":44,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-09-30T18:02:31.678Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/huggingface.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-01-12T18:03:00.000Z","updated_at":"2025-09-29T14:03:15.000Z","dependencies_parsed_at":"2024-03-12T19:08:21.083Z","dependency_job_id":"b79c7c5f-d6e0-4715-b5bb-b2a64b87d982","html_url":"https://github.com/huggingface/text-clustering","commit_stats":null,"previous_names":["huggingface/text-clustering"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/huggingface/text-clustering","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huggingface%2Ftext-clustering","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huggingface%2Ftext-clustering/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huggingface%2Ftext-clustering/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huggingface%2Ftext-clustering/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huggingface","download_url":"https://codeload.github.com/huggingface/text-clustering/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huggingface%2Ftext-clustering/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019316,"owners_count":26086711,"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-10-14T02:00:06.444Z","response_time":60,"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":[],"created_at":"2024-07-31T16:00:55.789Z","updated_at":"2025-10-14T15:30:05.385Z","avatar_url":"https://github.com/huggingface.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Text Clustering\n\nThe Text Clustering repository contains tools to easily embed and cluster texts as well as label clusters semantically. This repository is a work in progress and serves as a minimal codebase that can be modified and adapted to other use cases.\n\n\u003ccenter\u003e\u003cimg src=\"https://cdn-uploads.huggingface.co/production/uploads/61c141342aac764ce1654e43/jMKGaE_UnEfH3j8iZYXVN.png\"\u003e\u003c/center\u003e\n\u003ccenter\u003eClustering of texts in the \u003ca href=\"https://huggingface.co/datasets/HuggingFaceTB/cosmopedia\"\u003eCosmopedia dataset\u003c/a\u003e.\u003c/center\u003e\n\n\n## How it works\nThe pipeline consists of several distinct blocks that can be customized and the whole pipeline can run in a few minutes on a consumer laptop. Each block uses existing standard methods and works quite robustly.\n\n\u003ccenter\u003e\u003cimg src=\"https://huggingface.co/datasets/lvwerra/admin/resolve/main/text-clustering.png\"\u003e\u003c/center\u003e\n\u003ccenter\u003eText clustering pipeline.\u003c/center\u003e\n\n\n## Install \nInstall the following libraries to get started:\n```bash\npip install scikit-learn umap-learn sentence_transformers faiss-cpu plotly matplotlib datasets\n```\nClone this repository and navigate to the folder:\n```bash\ngit clone https://github.com/huggingface/text-clustering.git\ncd text-clustering\n```\n\n## Usage\n\nRun pipeline and visualize results:\n\n```python\nfrom src.text_clustering import ClusterClassifier\nfrom datasets import load_dataset\n\nSAMPLE = 100_000\n\ntexts = load_dataset(\"HuggingFaceTB/cosmopedia-100k\", split=\"train\").select(range(SAMPLE))[\"text\"]\n\ncc = ClusterClassifier(embed_device=\"mps\")\n\n# run the pipeline:\nembs, labels, summaries = cc.fit(texts)\n\n# show the results\ncc.show()\n\n# save \ncc.save(\"./cc_100k\")\n```\n\nLoad classifier and run inference:\n```python\nfrom src.text_clustering import ClusterClassifier\n\ncc = ClusterClassifier(embed_device=\"mps\")\n\n# load state\ncc.load(\"./cc_100k\")\n\n# visualize\ncc.show()\n\n# classify new texts with k-nearest neighbour search\ncluster_labels, embeddings = cc.infer(some_texts, top_k=1)\n```\n\nIf you want to reproduce the color scheme in the plot above you can add the following code before you run `cc.show()`:\n```python\nfrom cycler import cycler\nimport matplotlib.pyplot as plt\n\ndefault_cycler = (cycler(color=[\n    \"0F0A0A\",\n    \"FF6600\",\n    \"FFBE00\",\n    \"496767\",\n    \"87A19E\",\n    \"FF9200\",\n    \"0F3538\",\n    \"F8E08E\",\n    \"0F2021\",\n    \"FAFAF0\"])\n    )\nplt.rc('axes', prop_cycle=default_cycler)\n```\nIf you would like to customize the plotting further the easiest way is to customize or overwrite the `_show_mpl` and `_show_plotly` methods.\n\nYou can also run the pipeline using a script with:\n```bash\n# run a new pipeline\npython run_pipeline.py --mode run  --save_load_path './cc_100k' --n_samples 100000 --build_hf_ds\n# load existing pipeline\npython run_pipeline.py --mode load --save_load_path './cc_100k' --build_hf_ds\n# inference mode on new texts from an input dataset\npython run_pipeline.py --mode infer --save_load_path './cc_100k'  --n_samples \u003cNB_INFERENCE_SAMPLES\u003e --input_dataset \u003cHF_DATA_FOR_INFERENCE\u003e\n```\nThe `build_hf_ds` flag builds and pushes HF datasets, for the files and clusters, that can be directly used in the FW visualization space. In `infer` mode, we push the clusters dataset by default.\n\nYou can also change how the clusters are labeled (multiple topics (default) vs single topic with an educational score) using the flag `--topic_mode`.\n\n## Examples\n\nCheck the `examples` folder for an example of clustering and topic labeling applied to the [AutoMathText](https://huggingface.co/datasets/math-ai/AutoMathText/) dataset, utilizing [Cosmopedia](https://huggingface.co/datasets/HuggingFaceTB/cosmopedia)'s web labeling approach.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuggingface%2Ftext-clustering","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuggingface%2Ftext-clustering","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuggingface%2Ftext-clustering/lists"}