# chunkingman
> Biblioteca en Python para segmentar textos con múltiples estrategias: por tokens, semántica, LLM y métodos híbridos.
[](https://pypi.org/project/chunkingman/)
[](#requisitos)
[](#licencia)
`chunkingman` facilita dividir textos largos en fragmentos semánticamente coherentes usando varias técnicas escalables.
---
## Contenido
- [Instalación](#instalación)
- [Requisitos](#requisitos)
- [Configuración de credenciales](#configuración-de-credenciales)
- [Ejemplos de uso](#ejemplos-de-uso)
- [Elegir la estrategia adecuada](#elegir-la-estrategia-adecuada)
- [Buenas prácticas](#buenas-prácticas)
- [Roadmap](#roadmap)
- [Contribuir](#contribuir)
- [Licencia](#licencia)
---
## Instalación
```bash
pip install chunkingman
```
*Recomendado usar un entorno virtual (venv, conda, etc.).*
---
## Requisitos
- Python **3.12 o superior**
- Dependencias runtime (instaladas automáticamente): `rapidfuzz`, `chromadb`, `tiktoken`, `sentence-transformers`, `numpy`, `backoff`, `tqdm`, `openai`, `anthropic`, `attrs`
### Requisitos adicionales según funciones usadas:
- **Embeddings o LLM OpenAI**: exporta `OPENAI_API_KEY`
- **LLMs Anthropic**: exporta `ANTHROPIC_API_KEY`
---
## Configuración de credenciales
Puedes usar un archivo `.env`:
```
OPENAI_API_KEY=TU_CLAVE_OPENAI
ANTHROPIC_API_KEY=TU_CLAVE_ANTHROPIC
```
O exportarlas directamente en tu entorno:
```bash
export OPENAI_API_KEY="tu-clave"
export ANTHROPIC_API_KEY="tu-clave"
```
> Si utilizas `.env`, asegúrate de cargarlo (por ejemplo, con `python-dotenv`) antes de usar la librería.
---
## Ejemplos de uso
### 1. FixedTokenChunker
Corta los textos estrictamente según cantidad de tokens (útil para cumplir límites de contexto).
```python
from chunkingman.fixed_token_chunker import FixedTokenChunker
text = "Esto es un texto largo..."
chunker = FixedTokenChunker(chunk_size=800, chunk_overlap=100)
chunks = chunker.split_text(text)
```
---
### 2. RecursiveTokenChunker
Usa divisores jerárquicos (párrafos → líneas → oraciones → palabras) para preservar coherencia.
```python
from chunkingman.recursive_token_chunker import RecursiveTokenChunker
chunker = RecursiveTokenChunker(chunk_size=300, chunk_overlap=0)
chunks = chunker.split_text(text)
```
---
### 3. ClusterSemanticChunker
Convierten fragmentos en embeddings, calculan similitud y aplican DP con penalización optimizada.
```python
from chunkingman.cluster_semantic_chunker import ClusterSemanticChunker
from chunkingman.utils import get_embedding_function
emb_fn = get_embedding_function(
model_name="BAAI/bge-m3", # puedes cambiar por gte-large, e5-large-v2, etc.
device="cpu" # o "cuda" si tienes GPU
)
chunker = ClusterSemanticChunker(
embedding_function=emb_fn,
max_chunk_size=800,
min_chunk_size=140,
lambda_penalty=5.0,
similarity_band=200,
)
chunks = chunker.split_text(text)
```
---
### 4. KamradtModifiedChunker
Agrupa por semántica para alcanzar un tamaño medio de chunk especificado.
```python
from chunkingman.kamradt_modified_chunker import KamradtModifiedChunker
chunker = KamradtModifiedChunker(avg_chunk_size=400, min_chunk_size=50)
chunks = chunker.split_text(text)
```
---
### 5. LLMSemanticChunker
Delega en un LLM (OpenAI / Anthropic) la sugerencia de cortes temáticos.
```python
from chunkingman.llm_semantic_chunker import LLMSemanticChunker
chunker = LLMSemanticChunker(organisation="openai", model_name="gpt-4o")
chunks = chunker.split_text(text)
```
---
## ¿Cómo elegir la estrategia correcta?
| Estrategia | Cuándo usarla |
|---------------------------|---------------------------------------------------------|
| FixedTokenChunker | Necesitas límites de tokens estrictos. |
| RecursiveTokenChunker | Quieres cortes naturales sin embeddings. |
| ClusterSemanticChunker | Buscas cohesión semántica con embeddings. |
| KamradtModifiedChunker | Prefieres chunks de tamaño medio optimizado. |
| LLMSemanticChunker | Deseas cortes temáticos propuestos por un LLM. |
---
## Buenas prácticas
- Cuenta tokens con `tiktoken` para garantizar validez frente a modelos LLM.
- Usa `rapidfuzz` por rendimiento y compatibilidad API con `fuzzywuzzy`.
- Carga tus credenciales desde entorno o `.env` (no hardcodeadas).
- Usa tamaño de chunk acorde al modelo de embeddings o LLM que uses.
---
## Roadmap
- Benchmarks entre distintos chunkers.
- Configuración de *Trusted Publishers* para publicación CI/CD.
- Plugins de visualización e integración (CLI, exportación, metadatos, etc.).
---
## Contribuir
¡Tu ayuda es bienvenida!
1. Fork del repo
2. Crea una rama (`git checkout -b mi-feature`)
3. Añade tests y documentación
4. Abre un pull request
```bash
git clone https://github.com/romanpert/chunkingman
cd chunkingman
pip install -e ".[dev]"
pytest -q
```
---
## Licencia
Licenciado bajo **Apache License 2.0** — consulta el archivo `LICENSE` para más información.
Raw data
{
"_id": null,
"home_page": null,
"name": "chunkingman",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "chunking, text-splitting, embeddings, semantic, openai, nlp",
"author": null,
"author_email": "Rom\u00e1n P\u00e9rez Dumpert <roman.p98@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/49/51/0db3369ba19b87337ff70f27c941f7c3e4a9162be2f5d4d2200442e62923/chunkingman-0.0.3.tar.gz",
"platform": null,
"description": "# chunkingman\r\n\r\n> Biblioteca en Python para segmentar textos con m\u00faltiples estrategias: por tokens, sem\u00e1ntica, LLM y m\u00e9todos h\u00edbridos.\r\n\r\n[](https://pypi.org/project/chunkingman/) \r\n[](#requisitos) \r\n[](#licencia)\r\n\r\n`chunkingman` facilita dividir textos largos en fragmentos sem\u00e1nticamente coherentes usando varias t\u00e9cnicas escalables.\r\n\r\n---\r\n\r\n## Contenido\r\n\r\n- [Instalaci\u00f3n](#instalaci\u00f3n)\r\n- [Requisitos](#requisitos)\r\n- [Configuraci\u00f3n de credenciales](#configuraci\u00f3n-de-credenciales)\r\n- [Ejemplos de uso](#ejemplos-de-uso)\r\n- [Elegir la estrategia adecuada](#elegir-la-estrategia-adecuada)\r\n- [Buenas pr\u00e1cticas](#buenas-pr\u00e1cticas)\r\n- [Roadmap](#roadmap)\r\n- [Contribuir](#contribuir)\r\n- [Licencia](#licencia)\r\n\r\n---\r\n\r\n## Instalaci\u00f3n\r\n\r\n```bash\r\npip install chunkingman\r\n```\r\n\r\n*Recomendado usar un entorno virtual (venv, conda, etc.).*\r\n\r\n---\r\n\r\n## Requisitos\r\n\r\n- Python **3.12 o superior** \r\n- Dependencias runtime (instaladas autom\u00e1ticamente): `rapidfuzz`, `chromadb`, `tiktoken`, `sentence-transformers`, `numpy`, `backoff`, `tqdm`, `openai`, `anthropic`, `attrs`\r\n\r\n### Requisitos adicionales seg\u00fan funciones usadas:\r\n\r\n- **Embeddings o LLM OpenAI**: exporta `OPENAI_API_KEY` \r\n- **LLMs Anthropic**: exporta `ANTHROPIC_API_KEY`\r\n\r\n---\r\n\r\n## Configuraci\u00f3n de credenciales\r\n\r\nPuedes usar un archivo `.env`:\r\n\r\n```\r\nOPENAI_API_KEY=TU_CLAVE_OPENAI\r\nANTHROPIC_API_KEY=TU_CLAVE_ANTHROPIC\r\n```\r\n\r\nO exportarlas directamente en tu entorno:\r\n\r\n```bash\r\nexport OPENAI_API_KEY=\"tu-clave\"\r\nexport ANTHROPIC_API_KEY=\"tu-clave\"\r\n```\r\n\r\n> Si utilizas `.env`, aseg\u00farate de cargarlo (por ejemplo, con `python-dotenv`) antes de usar la librer\u00eda.\r\n\r\n---\r\n\r\n## Ejemplos de uso\r\n\r\n### 1. FixedTokenChunker\r\nCorta los textos estrictamente seg\u00fan cantidad de tokens (\u00fatil para cumplir l\u00edmites de contexto).\r\n\r\n```python\r\nfrom chunkingman.fixed_token_chunker import FixedTokenChunker\r\n\r\ntext = \"Esto es un texto largo...\"\r\nchunker = FixedTokenChunker(chunk_size=800, chunk_overlap=100)\r\nchunks = chunker.split_text(text)\r\n```\r\n\r\n---\r\n\r\n### 2. RecursiveTokenChunker\r\nUsa divisores jer\u00e1rquicos (p\u00e1rrafos \u2192 l\u00edneas \u2192 oraciones \u2192 palabras) para preservar coherencia.\r\n\r\n```python\r\nfrom chunkingman.recursive_token_chunker import RecursiveTokenChunker\r\n\r\nchunker = RecursiveTokenChunker(chunk_size=300, chunk_overlap=0)\r\nchunks = chunker.split_text(text)\r\n```\r\n\r\n---\r\n\r\n### 3. ClusterSemanticChunker\r\nConvierten fragmentos en embeddings, calculan similitud y aplican DP con penalizaci\u00f3n optimizada.\r\n\r\n```python\r\nfrom chunkingman.cluster_semantic_chunker import ClusterSemanticChunker\r\nfrom chunkingman.utils import get_embedding_function\r\n\r\nemb_fn = get_embedding_function(\r\n model_name=\"BAAI/bge-m3\", # puedes cambiar por gte-large, e5-large-v2, etc.\r\n device=\"cpu\" # o \"cuda\" si tienes GPU\r\n)\r\n\r\nchunker = ClusterSemanticChunker(\r\n embedding_function=emb_fn,\r\n max_chunk_size=800,\r\n min_chunk_size=140,\r\n lambda_penalty=5.0,\r\n similarity_band=200,\r\n)\r\n\r\nchunks = chunker.split_text(text)\r\n```\r\n\r\n---\r\n\r\n### 4. KamradtModifiedChunker\r\nAgrupa por sem\u00e1ntica para alcanzar un tama\u00f1o medio de chunk especificado.\r\n\r\n```python\r\nfrom chunkingman.kamradt_modified_chunker import KamradtModifiedChunker\r\n\r\nchunker = KamradtModifiedChunker(avg_chunk_size=400, min_chunk_size=50)\r\nchunks = chunker.split_text(text)\r\n```\r\n\r\n---\r\n\r\n### 5. LLMSemanticChunker\r\nDelega en un LLM (OpenAI / Anthropic) la sugerencia de cortes tem\u00e1ticos.\r\n\r\n```python\r\nfrom chunkingman.llm_semantic_chunker import LLMSemanticChunker\r\n\r\nchunker = LLMSemanticChunker(organisation=\"openai\", model_name=\"gpt-4o\")\r\nchunks = chunker.split_text(text)\r\n```\r\n\r\n---\r\n\r\n## \u00bfC\u00f3mo elegir la estrategia correcta?\r\n\r\n| Estrategia | Cu\u00e1ndo usarla |\r\n|---------------------------|---------------------------------------------------------|\r\n| FixedTokenChunker | Necesitas l\u00edmites de tokens estrictos. |\r\n| RecursiveTokenChunker | Quieres cortes naturales sin embeddings. |\r\n| ClusterSemanticChunker | Buscas cohesi\u00f3n sem\u00e1ntica con embeddings. |\r\n| KamradtModifiedChunker | Prefieres chunks de tama\u00f1o medio optimizado. |\r\n| LLMSemanticChunker | Deseas cortes tem\u00e1ticos propuestos por un LLM. |\r\n\r\n---\r\n\r\n## Buenas pr\u00e1cticas\r\n\r\n- Cuenta tokens con `tiktoken` para garantizar validez frente a modelos LLM.\r\n- Usa `rapidfuzz` por rendimiento y compatibilidad API con `fuzzywuzzy`.\r\n- Carga tus credenciales desde entorno o `.env` (no hardcodeadas).\r\n- Usa tama\u00f1o de chunk acorde al modelo de embeddings o LLM que uses.\r\n\r\n---\r\n\r\n## Roadmap\r\n\r\n- Benchmarks entre distintos chunkers.\r\n- Configuraci\u00f3n de *Trusted Publishers* para publicaci\u00f3n CI/CD.\r\n- Plugins de visualizaci\u00f3n e integraci\u00f3n (CLI, exportaci\u00f3n, metadatos, etc.).\r\n\r\n---\r\n\r\n## Contribuir\r\n\r\n\u00a1Tu ayuda es bienvenida! \r\n1. Fork del repo \r\n2. Crea una rama (`git checkout -b mi-feature`) \r\n3. A\u00f1ade tests y documentaci\u00f3n \r\n4. Abre un pull request\r\n\r\n```bash\r\ngit clone https://github.com/romanpert/chunkingman\r\ncd chunkingman\r\npip install -e \".[dev]\"\r\npytest -q\r\n```\r\n\r\n---\r\n\r\n## Licencia\r\n\r\nLicenciado bajo **Apache License 2.0** \u2014 consulta el archivo `LICENSE` para m\u00e1s informaci\u00f3n.\r\n",
"bugtrack_url": null,
"license": "Apache License\r\n Version 2.0, January 2004\r\n http://www.apache.org/licenses/\r\n \r\n Copyright 2025 Rom\u00e1n\r\n \r\n Licensed under the Apache License, Version 2.0 (the \"License\");\r\n you may not use this file except in compliance with the License.\r\n You may obtain a copy of the License at\r\n \r\n http://www.apache.org/licenses/LICENSE-2.0\r\n \r\n Unless required by applicable law or agreed to in writing, software\r\n distributed under the License is distributed on an \"AS IS\" BASIS,\r\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\n See the License for the specific language governing permissions and\r\n limitations under the License.\r\n ",
"summary": "A library for various text chunking strategies, including token-based, semantic, LLM-guided and hybrid approaches.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/romanpert/chunkingman",
"Issues": "https://github.com/romanpert/chunkingman/issues",
"Repository": "https://github.com/romanpert/chunkingman"
},
"split_keywords": [
"chunking",
" text-splitting",
" embeddings",
" semantic",
" openai",
" nlp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0760f6c2570d73fcdd063c97824df3f0b4de586a325f14615c45918b0054b3e4",
"md5": "cc78310019a890fe77a4b3a8ca596136",
"sha256": "85ca0a369e5eb282609f93f4fc694035dfd1fd8256a6422d60ca0abfb74e99f6"
},
"downloads": -1,
"filename": "chunkingman-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc78310019a890fe77a4b3a8ca596136",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 21773,
"upload_time": "2025-08-28T17:48:59",
"upload_time_iso_8601": "2025-08-28T17:48:59.492034Z",
"url": "https://files.pythonhosted.org/packages/07/60/f6c2570d73fcdd063c97824df3f0b4de586a325f14615c45918b0054b3e4/chunkingman-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "49510db3369ba19b87337ff70f27c941f7c3e4a9162be2f5d4d2200442e62923",
"md5": "d09bf4f671d76d7836717c0bdf1d3cd4",
"sha256": "bb8dd2c9ddd9e61e91bea4708fea463d06b9c7db05f09d386e8c979ea2e42b12"
},
"downloads": -1,
"filename": "chunkingman-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "d09bf4f671d76d7836717c0bdf1d3cd4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 21281,
"upload_time": "2025-08-28T17:49:00",
"upload_time_iso_8601": "2025-08-28T17:49:00.366335Z",
"url": "https://files.pythonhosted.org/packages/49/51/0db3369ba19b87337ff70f27c941f7c3e4a9162be2f5d4d2200442e62923/chunkingman-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:49:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "romanpert",
"github_project": "chunkingman",
"github_not_found": true,
"lcname": "chunkingman"
}
