| Name | llm-cluster-optimizer JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | A drop-in replacement for sklearn clustering models, this package optimizes sklearn clusters using LLMs |
| upload_time | 2024-09-04 22:31:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 Noah Santacruz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
llm
kmeans
text clustering
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## llm-cluster-optimizer
A drop-in replacement for sklearn clustering models, this package optimizes sklearn clusters using LLMs
## Installation
By default, this package relies on OpenAI for LLM interactions. This requires having copying your API key from [here](https://platform.openai.com/account/api-keys) and putting it in the `OPENAI_API_KEY` envvar.
Otherwise, you can use any other LLM provider, as described below.
To install `llm-cluster-optimizer`, run the following command in your terminal:
```shell
pip install llm-cluster-optimizer
```
## Usage
Here is a simple example of usage that provides two cluster models as options to be optimized. `labels` will be an `np.ndarray` of shape `(len(input_texts),)` representing which cluster each input text falls into. Use `verbose=True` in `LLMClusterOptimizer.__init__()` to get more information on progress.
```python
from llm_cluster_optimizer import LLMClusterOptimizer
from sklearn.cluster import AffinityPropagation, HDBSCAN
import numpy as np
from langchain_openai import OpenAIEmbeddings
def embed_text_openai(text):
return np.array(OpenAIEmbeddings(model="text-embedding-3-large").embed_query(text))
model = HDBSCAN(min_cluster_size=2, min_samples=1),
optimizer = LLMClusterOptimizer(model, embed_text_openai, 0.3)
input_texts = [] # your list of input texts
labels = optimizer.fit_predict_text(input_texts)
```
To use a clustering algorithm that takes the number of clusters as an input, you likely want to optimize `n` using the silhouette score or a similar metric. This requires access to the embeddings. You can pass the model wrapped in a function to achieve this:
```python
from sklearn.cluster import KMeans
from util import guess_optimal_n_clusters
def get_kmeans_model(embeddings: np.ndarray):
n_clusters = guess_optimal_n_clusters(embeddings, lambda n: KMeans(n_clusters=n))
return KMeans(n_clusters=n_clusters)
optimizer = LLMClusterOptimizer(get_kmeans_model, embed_text_openai, 0.3)
```
## Docs
### __init__()
| **Param** | **Description** | **Default** | **Type** |
|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| `cluster_model` | SKlearn cluster model instance (aka ClusterMixin). Can be either a ClusterMixin or a Callable that takes a list of embeddings and returns a ClusterMixin. Use the latter if the ClusterMixin requires n clusters as a parameter. The callable should use the embeddings to determine the optimal n. See `util.guess_optimal_n_clusters()` as an example for calcualting optimal number of clusters. | N/A | `Union[ClusterMixin, Callable[[ndarray], ClusterMixin]]` |
| `embedding_fn` | Function that takes a string and returns its embedding. | N/A | `Callable[[str], ndarray]` |
| `threshold_to_combine` | Float that represents the maximum cosine distance between cluster summary embeddings where clusters should be combined. | N/A | `Callable[[int], int]` |
| `recluster_threshold_fn` | Function that takes the number of input texts and outputs the minimum size cluster that will be reclustered using `cluster_model`. If not provided, the minimum size is the square root of input size (implying uniform distribution of cluster sizes). | `lambda x: round(math.sqrt(x)))` | `Callable[[int], int]` |
| `get_cluster_summary` | Function that takes a list of strings which are samples from a cluster and returns a summary of them. See `default` for default functionality. Requires OpenAI API key in envvars if using default. | Uses GPT-4o-mini to summarize strings sampled from the cluster. Summary will be no more than 10 words. | `Callable[[list[str]], str]` |
| `summary_sample_size` | Number of items to sample from a cluster. | `5` | `int` |
| `num_summarization_workers` | Number of workers to use when running `get_cluster_summary()`. Be aware of rate limits depending on the LLM provider being used. | `25` | `int` |
| `num_embed_workers` | Number of workers to use when running `embedding_fn()`. Be aware of rate limits depending on the LLM provider being used. | `50` | `int` |
| `verbose` | Output logs to console. | `True` | `bool` |
### fit_predict_text()
Mimics `sklearn.base.ClusterMixin.fit_predict()`. Given a sequence of texts, returns the cluster labels for each text.
Chooses best of `cluster_models` passed in `__init__()` based on `calculate_clustering_score()`
Post-processes clusters so that:
- large clusters are broken up
- small clusters are combined based on similarity
| **Param** | **Description** | **Default** | **Type** |
|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------|
| `texts` | List of strings to cluster | N/A | `list[str]` |
Raw data
{
"_id": null,
"home_page": null,
"name": "llm-cluster-optimizer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "LLM, kmeans, text clustering",
"author": null,
"author_email": "Noah Santacruz <noahssantacruz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/20/c56bcbfef17eddcd567c20e65fcbd7d588810946b8ff15dcb10d57a783bd/llm_cluster_optimizer-1.0.4.tar.gz",
"platform": null,
"description": "## llm-cluster-optimizer\n\nA drop-in replacement for sklearn clustering models, this package optimizes sklearn clusters using LLMs\n\n## Installation\n\nBy default, this package relies on OpenAI for LLM interactions. This requires having copying your API key from [here](https://platform.openai.com/account/api-keys) and putting it in the `OPENAI_API_KEY` envvar.\n\nOtherwise, you can use any other LLM provider, as described below.\n\nTo install `llm-cluster-optimizer`, run the following command in your terminal:\n\n```shell\npip install llm-cluster-optimizer\n```\n\n## Usage\n\nHere is a simple example of usage that provides two cluster models as options to be optimized. `labels` will be an `np.ndarray` of shape `(len(input_texts),)` representing which cluster each input text falls into. Use `verbose=True` in `LLMClusterOptimizer.__init__()` to get more information on progress.\n\n```python\nfrom llm_cluster_optimizer import LLMClusterOptimizer\nfrom sklearn.cluster import AffinityPropagation, HDBSCAN\nimport numpy as np\nfrom langchain_openai import OpenAIEmbeddings\n\ndef embed_text_openai(text):\n return np.array(OpenAIEmbeddings(model=\"text-embedding-3-large\").embed_query(text))\n\nmodel = HDBSCAN(min_cluster_size=2, min_samples=1),\noptimizer = LLMClusterOptimizer(model, embed_text_openai, 0.3)\n\ninput_texts = [] # your list of input texts\nlabels = optimizer.fit_predict_text(input_texts)\n```\n\nTo use a clustering algorithm that takes the number of clusters as an input, you likely want to optimize `n` using the silhouette score or a similar metric. This requires access to the embeddings. You can pass the model wrapped in a function to achieve this:\n\n```python\nfrom sklearn.cluster import KMeans\nfrom util import guess_optimal_n_clusters\n\ndef get_kmeans_model(embeddings: np.ndarray):\n n_clusters = guess_optimal_n_clusters(embeddings, lambda n: KMeans(n_clusters=n))\n return KMeans(n_clusters=n_clusters)\n\n\noptimizer = LLMClusterOptimizer(get_kmeans_model, embed_text_openai, 0.3)\n```\n\n## Docs\n\n### __init__()\n\n| **Param** | **Description** | **Default** | **Type** |\n|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|\n| `cluster_model` | SKlearn cluster model instance (aka ClusterMixin). Can be either a ClusterMixin or a Callable that takes a list of embeddings and returns a ClusterMixin. Use the latter if the ClusterMixin requires n clusters as a parameter. The callable should use the embeddings to determine the optimal n. See `util.guess_optimal_n_clusters()` as an example for calcualting optimal number of clusters. | N/A | `Union[ClusterMixin, Callable[[ndarray], ClusterMixin]]` |\n| `embedding_fn` | Function that takes a string and returns its embedding. | N/A | `Callable[[str], ndarray]` |\n| `threshold_to_combine` | Float that represents the maximum cosine distance between cluster summary embeddings where clusters should be combined. | N/A | `Callable[[int], int]` |\n| `recluster_threshold_fn` | Function that takes the number of input texts and outputs the minimum size cluster that will be reclustered using `cluster_model`. If not provided, the minimum size is the square root of input size (implying uniform distribution of cluster sizes). | `lambda x: round(math.sqrt(x)))` | `Callable[[int], int]` |\n| `get_cluster_summary` | Function that takes a list of strings which are samples from a cluster and returns a summary of them. See `default` for default functionality. Requires OpenAI API key in envvars if using default. | Uses GPT-4o-mini to summarize strings sampled from the cluster. Summary will be no more than 10 words. | `Callable[[list[str]], str]` |\n| `summary_sample_size` | Number of items to sample from a cluster. | `5` | `int` |\n| `num_summarization_workers` | Number of workers to use when running `get_cluster_summary()`. Be aware of rate limits depending on the LLM provider being used. | `25` | `int` |\n| `num_embed_workers` | Number of workers to use when running `embedding_fn()`. Be aware of rate limits depending on the LLM provider being used. | `50` | `int` |\n| `verbose` | Output logs to console. | `True` | `bool` |\n\n\n### fit_predict_text()\n\nMimics `sklearn.base.ClusterMixin.fit_predict()`. Given a sequence of texts, returns the cluster labels for each text.\nChooses best of `cluster_models` passed in `__init__()` based on `calculate_clustering_score()`\nPost-processes clusters so that:\n- large clusters are broken up\n- small clusters are combined based on similarity\n\n| **Param** | **Description** | **Default** | **Type** |\n|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|---------------------------------------------------------------------------|\n| `texts` | List of strings to cluster | N/A | `list[str]` |",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Noah Santacruz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A drop-in replacement for sklearn clustering models, this package optimizes sklearn clusters using LLMs",
"version": "1.0.4",
"project_urls": {
"Homepage": "https://github.com/nsantacruz/LLMClusterOptimizer",
"Issues": "https://github.com/nsantacruz/LLMClusterOptimizer/issues"
},
"split_keywords": [
"llm",
" kmeans",
" text clustering"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ad18e13a47b5592838309bebf8bfdeb386378b24c33ffcd0d6724d87f9c8684",
"md5": "0c30a42fe3f9c9b355a2a36de49b72eb",
"sha256": "e97a4d7c2bd13b787212b799be2db9cf5cae6a1d2fa9f31a8981243ac4e98a27"
},
"downloads": -1,
"filename": "llm_cluster_optimizer-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c30a42fe3f9c9b355a2a36de49b72eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11033,
"upload_time": "2024-09-04T22:31:33",
"upload_time_iso_8601": "2024-09-04T22:31:33.935325Z",
"url": "https://files.pythonhosted.org/packages/1a/d1/8e13a47b5592838309bebf8bfdeb386378b24c33ffcd0d6724d87f9c8684/llm_cluster_optimizer-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7a20c56bcbfef17eddcd567c20e65fcbd7d588810946b8ff15dcb10d57a783bd",
"md5": "55d2135491890f07b06547ca1d0dc2bb",
"sha256": "d346ef25d2a88d367bc6b203c1e74749de9ffa67d2fe9261db8b8471e46e920c"
},
"downloads": -1,
"filename": "llm_cluster_optimizer-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "55d2135491890f07b06547ca1d0dc2bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8017,
"upload_time": "2024-09-04T22:31:35",
"upload_time_iso_8601": "2024-09-04T22:31:35.580200Z",
"url": "https://files.pythonhosted.org/packages/7a/20/c56bcbfef17eddcd567c20e65fcbd7d588810946b8ff15dcb10d57a783bd/llm_cluster_optimizer-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 22:31:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nsantacruz",
"github_project": "LLMClusterOptimizer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "llm-cluster-optimizer"
}
