Registry / llm-agents / semantic-text-splitter

semantic-text-splitter

JSON →
library0.31.0pypypi✓ verified 83d ago

The `semantic-text-splitter` Python library provides advanced text splitting capabilities by leveraging semantic embeddings to create semantically coherent document chunks. It builds upon `sentence-transformers` and `transformers` to offer both character-based and embedding-based splitting. The current version is 0.29.0, with a relatively frequent release cadence, often introducing new features or refinements every few weeks.

pip install semantic-text-splitter
INSTALL
IMPORT
SIG · SEMANTIC-TEXT-SPLI
S
semantic-text-splitter
llm-agentspythonv0.31.0
Install
1.9s avg
Import
Disk
34MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.31.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
build_error
glibc
py 3.103.940 runs
installs and imports cleanly · install 1.9s · import 0.000s · 37MB
34MB installed
● package 34MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TextSplitter
from semantic_text_splitter import TextSplitter
from semantic_text_splitter import EmbeddingTextSplitter
CodeSplitter
from semantic_text_splitter import CodeSplitter
MarkdownSplitter
from semantic_text_splitter import MarkdownSplitter

This quickstart demonstrates how to use `EmbeddingTextSplitter` to divide a long document into semantically related chunks using a pre-trained embedding model and its corresponding tokenizer. It also shows `CharacterTextSplitter` for comparison.

import os from semantic_text_splitter import EmbeddingTextSplitter from transformers import AutoTokenizer # Example text, often a full document long_document_text = ( "The quick brown fox jumps over the lazy dog. " "This sentence is a classic example used for typing practice. " "However, its semantic content is rather limited. " "In natural language processing, we often deal with much longer texts, " "requiring sophisticated methods to break them into manageable pieces. " "Semantic text splitting aims to keep related ideas together, " "even if they are separated by punctuation or line breaks. " "This is crucial for retrieval augmented generation (RAG) systems. " "By using embeddings, the splitter can understand the meaning of the text " "and make informed decisions about where to cut." * 5 # Repeat to make it long enough for splitting ) # Choose an embedding model (e.g., from Hugging Face Hub) # Ensure this model is suitable for your language and task model_name = "BAAI/bge-small-en-v1.5" # Initialize the tokenizer for the chosen model # This is crucial for accurate token counting tokenizer = AutoTokenizer.from_pretrained(model_name) # Initialize the EmbeddingTextSplitter # 'threshold' controls semantic similarity: higher = more similar chunks # 'max_tokens' defines the maximum size of each chunk embedding_splitter = EmbeddingTextSplitter( tokenizer=tokenizer, model_name=model_name, threshold=0.5, max_tokens=256 ) # Split the document into semantically coherent chunks embedding_chunks = embedding_splitter.chunks(long_document_text) print(f"Original text length: {len(long_document_text)} characters") print(f"Number of chunks created: {len(embedding_chunks)}") if embedding_chunks: print(f"First chunk (length {len(embedding_chunks[0])} chars):\n---\n{embedding_chunks[0]}\n---") print(f"Last chunk (length {len(embedding_chunks[-1])} chars):\n---\n{embedding_chunks[-1]}\n---") # Example of CharacterTextSplitter (simpler, non-semantic) from semantic_text_splitter import CharacterTextSplitter character_splitter = CharacterTextSplitter( tokenizer=tokenizer, chunk_size=256, chunk_overlap=30 ) char_chunks = character_splitter.chunks(long_document_text) print(f"\nNumber of character chunks created: {len(char_chunks)}") if char_chunks: print(f"First char chunk (length {len(char_chunks[0])} chars):\n---\n{char_chunks[0]}\n---")
Debug
Known issues
gotchaPrior to version 0.14.0, `EmbeddingTextSplitter` might have implicitly handled tokenizer loading. Since v0.14.0, a `tokenizer` argument (from `transformers.AutoTokenizer`) is explicitly required during initialization, which is a common source of `TypeError` if not provided.
fix
Always initialize your `EmbeddingTextSplitter` with `tokenizer=AutoTokenizer.from_pretrained(model_name)` alongside `model_name`.
affects: <0.14.0 to >=0.14.0
breakingVersion 0.28.0 refactored how embedding models are loaded, primarily relying on `sentence-transformers` for robustness and direct compatibility. Custom embedding functions or older integration patterns that bypassed `model_name` might no longer work as expected.
fix
Ensure you are passing a `model_name` compatible with `sentence-transformers` (e.g., from Hugging Face Hub). If using custom embedding logic, review the library's `_get_embeddings` method for current expected inputs.
affects: <0.28.0 to >=0.28.0
gotchaProcessing very large documents or using large `max_tokens` with GPU-enabled embedding models can lead to `RuntimeError: CUDA error: out of memory`. This is especially true if running on a limited VRAM GPU.
fix
Reduce `max_tokens`, process text in smaller batches before passing to the splitter, or upgrade your GPU memory. Consider using CPU-only models or smaller models if memory is a significant constraint.
affects: All versions
gotchaThe `threshold` parameter in `EmbeddingTextSplitter` significantly impacts chunking behavior. A very high `threshold` can lead to many small chunks or even single-sentence chunks, while a very low `threshold` might result in excessively large chunks or not splitting at all, depending on the text's semantic density.
fix
Experiment with `threshold` values (e.g., 0.3 to 0.7 for common models like BGE) and `max_tokens` on a representative sample of your data to find an optimal balance for your use case.
affects: All versions
Upgrade
Version history
0.31.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
transformersrequiredRequired for tokenization (e.g., AutoTokenizer).
sentence-transformersrequiredRequired for embedding generation.
torchoptionalOften a dependency of sentence-transformers, required for GPU acceleration.
Agent activity
23 hits · last 30 days
node
18
OpenAI (training)
2
Amazon
1
Resources