Metadata-Version: 2.4
Name: trimwise
Version: 0.1.1
Summary: High-signal text trimming for better LLM prompts.
Keywords: llm,truncation,context,bm25,embeddings
Author: Aakash
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: markdown-it-py>=4.2,<5
Requires-Dist: numpy>=1.26,<3
Requires-Dist: tiktoken>=0.13,<1
Requires-Dist: build>=1.5,<2 ; extra == "dev"
Requires-Dist: mypy>=2.3,<3 ; extra == "dev"
Requires-Dist: pytest>=9.1,<10 ; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4,<2 ; extra == "dev"
Requires-Dist: pytest-cov>=7.1,<8 ; extra == "dev"
Requires-Dist: ruff>=0.15.21,<1 ; extra == "dev"
Requires-Dist: fastembed>=0.8,<1 ; extra == "semantic"
Requires-Dist: fastembed-gpu>=0.8,<1 ; extra == "semantic-gpu"
Project-URL: Issues, https://github.com/tenwritehq/trimwise/issues
Project-URL: Source, https://github.com/tenwritehq/trimwise
Provides-Extra: dev
Provides-Extra: semantic
Provides-Extra: semantic-gpu

# Trimwise

[![PyPI version](https://badge.fury.io/py/trimwise.svg)](https://pypi.org/project/trimwise/)

**Keep the most useful parts of long text before adding it to an LLM prompt.**

Trimwise creates compact, high-signal excerpts from documents, blog posts, search results you have
already fetched, logs, and tool output. Instead of keeping only `text[:N]`, it can select complete
fragments from across the source, reduce obvious repetition, and return everything inside an exact
token, word, or character limit.

The result remains extractive: retained text comes from your input, keeps its original wording, and
appears in source order. Trimwise does not search the web, retrieve documents, query a vector
database, or rewrite your evidence.

[Documentation](https://trimwise.readthedocs.io/en/latest/) ·
[Getting started](https://trimwise.readthedocs.io/en/latest/getting-started/) ·
[API reference](https://trimwise.readthedocs.io/en/latest/api-reference/) ·
[PyPI](https://pypi.org/project/trimwise/)

## Why use Trimwise?

Prefix truncation is fast, but it assumes the beginning contains the best information. Real sources
often put decisions, conclusions, error messages, identifiers, and examples much later.

```text
Prefix slicing:  [introduction -------------------------------] cut

Trimwise:        [opening context] [...omitted...] [important decision]
```

Trimwise is designed for prompt assembly:

- **Trim evidence, not instructions.** Keep your system prompt, task, and output schema unchanged.
- **Give every source a fair budget.** One large document cannot consume the space intended for
  every other source.
- **Keep evidence traceable.** Selected fragments stay verbatim and in their original order.
- **Select beyond the introduction.** Headings, paragraphs, lists, tables, code fences, sentences,
  and source lines can all become candidates.
- **Follow the task when one is known.** Use exact lexical matching, semantic similarity, or both.
- **Stay lightweight when embeddings are unnecessary.** Structural and lexical trimming need no
  embedding model.
- **Use research-grounded selection.** Trimwise combines BM25, centroid salience, sentence
  embeddings, score fusion, MMR, and adaptive evidence selection.

## Installation

Trimwise supports Python 3.10 through 3.14.

| What you need | `pip` | `uv` |
| --- | --- | --- |
| Structural, lexical, or your own embedding callback | `python -m pip install trimwise` | `uv add trimwise` |
| Trimwise-managed semantic models on CPU | `python -m pip install "trimwise[semantic]"` | `uv add "trimwise[semantic]"` |
| Trimwise-managed semantic models on NVIDIA GPU | `python -m pip install "trimwise[semantic-gpu]"` | `uv add "trimwise[semantic-gpu]"` |

The core installation includes Markdown parsing, token measurement, lexical ranking, and vector
scoring. It does not install FastEmbed or download an embedding model.

Do not install the CPU and GPU semantic extras together. GPU use also requires compatible CUDA and
cuDNN libraries. See [Semantic Models and Async Use](https://trimwise.readthedocs.io/en/latest/semantic-and-async/)
for callbacks, model loading, concurrency, and GPU details.

## Quick start

```python
from trimwise import Trimmer

document = """\
# Incident report

The service became unavailable at 09:14. Initial checks focused on the network.

## Root cause

The team traced the failure to an expired credential.

## Decision

Credentials will now rotate automatically every 30 days.
"""

result = Trimmer().trim(
    document,
    limit=24,
    query="What caused the outage and how will it be prevented?",
)

print(result.text)
print(result.output_count)  # Always <= 24
print(result.strategy)      # Strategy.LEXICAL: auto resolved from the query
```

`auto` uses structural coverage when no query is supplied and fast lexical BM25 when a query is
present. Neither path loads an embedding model. If the original input already fits, Trimwise
returns it byte-for-byte unchanged.

## Main use case: trim each source before building the prompt

Suppose an LLM must cluster many blog posts. Sending every full post may exceed the context window,
while `post[:N]` gives the model only introductions. Trim each post independently, then assemble the
prompt from the resulting excerpts:

```python
from pathlib import Path

from trimwise import Trimmer

instructions = """\
Cluster the blog posts by their main topic.
Give each cluster a short name and list its source numbers.
Base the answer only on the supplied excerpts.
"""

trimmer = Trimmer()
excerpts = []

for number, path in enumerate(sorted(Path("posts").glob("*.md")), start=1):
    source = path.read_text(encoding="utf-8")
    excerpt = trimmer.trim(source, limit=300, strategy="structural").text
    excerpts.append(f"## Source {number}: {path.name}\n{excerpt}")

prompt = instructions + "\n\n" + "\n\n".join(excerpts)
```

This keeps the prompt layers separate: instructions remain exact, every source gets its own
ceiling, and each excerpt can represent material from across its source. Labels, separators, and
instructions still consume space in the final prompt, so leave room for them when choosing each
source limit.

## Choose a strategy

| Strategy | Use it when | What it prioritizes |
| --- | --- | --- |
| `auto` | You want a safe default | `structural` without a query; `lexical` with one |
| `structural` | No question or task is available | Document centrality, section coverage, and fitting beginning/end units |
| `lexical` | Exact names, IDs, errors, URLs, or phrases matter | BM25 matches between the query and source fragments |
| `semantic` | The source may express the answer with different words or another supported language | Embedding similarity between the query and candidates |
| `hybrid` | Literal evidence and paraphrases both matter | An equal blend of normalized BM25 and semantic scores |

`lexical`, `semantic`, and `hybrid` require a nonblank query. Semantic and hybrid calls require
either your own embedding callback or one of the FastEmbed extras.

Query-aware strategies may stop below the requested limit when the remaining candidates appear
weakly related. The limit means “at most,” not “fill every token with progressively less useful
text.”

Read [Strategies](https://trimwise.readthedocs.io/en/latest/strategies/) for examples, scoring
behavior, and practical tradeoffs.

## Semantic trimming

You have two options.

### Let Trimwise manage the model

Install a semantic extra and request `semantic` or `hybrid` explicitly:

```python
from trimwise import Trimmer

result = Trimmer().trim(
    document,
    limit=500,
    strategy="hybrid",
    query="What caused incident ORION-774?",
)
```

The default multilingual model is downloaded and initialized on the first semantic call, then
reused by that `Trimmer`. Structural and lexical calls never load it.

### Bring your own embeddings

The core installation can use semantic and hybrid strategies without FastEmbed when you provide an
embedding callback. Use a synchronous callback with `trim()` or `atrim()`, or an asynchronous
callback with `atrim()` for an async embedding service.

Your callback receives the query separately from the candidate passages and returns one query
vector plus one same-dimension vector per passage. Trimwise validates and scores the vectors; your
model or client remains under your control.

See [Bring Your Own Embeddings](https://trimwise.readthedocs.io/en/latest/semantic-and-async/)
for complete synchronous and asynchronous examples.

## Budgets and configuration

Token budgets use Tiktoken and the `o200k_base` encoding by default:

```python
result = Trimmer().trim(document, limit=500)
```

Words and characters are available when tokens are not the unit you need:

```python
word_result = Trimmer().trim(document, limit=300, unit="words")
character_result = Trimmer().trim(document, limit=2_000, unit="characters")
```

Use `TrimConfig` for reusable behavior:

```python
from trimwise import TrimConfig, Trimmer

trimmer = Trimmer(
    TrimConfig(
        omission_marker="[content omitted]",
        mmr_lambda=0.75,
    )
)
```

You can also choose a Tiktoken encoding, FastEmbed model, inference batch size, and FastEmbed
options, or supply a custom token counter for token budgets. See
[Configuration and API](https://trimwise.readthedocs.io/en/latest/configuration-and-api/) for every
field, argument, validation rule, and result value.

## Async use

`atrim()` keeps parsing, measurement, ranking, model loading, inference, callbacks, and selection
from blocking the event loop:

```python
result = await Trimmer().atrim(
    document,
    limit=500,
    strategy="lexical",
    query="Which decision was approved?",
)
```

Cancellation stops waiting for the result but cannot terminate synchronous work already running in
a worker thread. Async embedding callbacks are awaited directly and can receive cancellation.

## What Trimwise guarantees

- The measured output never exceeds the requested limit.
- Input that already fits is returned byte-for-byte unchanged.
- Retained fragments use exact source text and appear in source order.
- Omission markers are added only when they fit; retained evidence takes priority.
- Closed code fences preserve their opening and closing fences during fallback when the fence shell
  itself fits.
- FastEmbed is never imported for structural, lexical, or already-fitting inputs.

Trimwise does not summarize, paraphrase, combine distant facts into a new sentence, or guarantee
that selected fragments contain different facts. MMR reduces vector similarity, which is a useful
proxy for repetition rather than factual proof. At extreme compression ratios, a trained or
abstractive compressor may preserve more answer-relevant information per token, but it gives up
Trimwise’s exact-source guarantee.

Read [Guarantees and Limitations](https://trimwise.readthedocs.io/en/latest/guarantees-and-limitations/)
for the precise boundaries.

## Research foundations

Trimwise adapts established methods to source-backed fragments and exact output budgets:

- BM25 for exact lexical relevance
- TF-IDF centroid similarity for queryless representativeness
- Sentence embeddings for semantic relevance
- Normalized convex fusion, with RRF as a fallback
- Maximal Marginal Relevance for reduced representational repetition
- Adaptive-k-inspired evidence boundaries for query-aware selection

These methods guide selection; they do not prove that every excerpt is optimal. The
[Research Foundations](https://trimwise.readthedocs.io/en/latest/research-foundations/) page maps
each idea to the current behavior, explains the user benefit, and states what the evidence does not
guarantee.

## Documentation

- [Getting Started](https://trimwise.readthedocs.io/en/latest/getting-started/)
- [Strategies](https://trimwise.readthedocs.io/en/latest/strategies/)
- [Semantic Models and Async Use](https://trimwise.readthedocs.io/en/latest/semantic-and-async/)
- [Configuration and API](https://trimwise.readthedocs.io/en/latest/configuration-and-api/)
- [How Trimwise Works](https://trimwise.readthedocs.io/en/latest/how-it-works/)
- [Guarantees and Limitations](https://trimwise.readthedocs.io/en/latest/guarantees-and-limitations/)
- [Research Foundations](https://trimwise.readthedocs.io/en/latest/research-foundations/)
- [API Reference](https://trimwise.readthedocs.io/en/latest/api-reference/)

Trimwise is available under the [MIT License](LICENSE).

