Trimwise

Query-aware compression within an exact budget.

Documentation · Getting started · API reference · PyPI

Trimwise is built for query-aware prompt assembly. Given a question, it selects the most useful exact source evidence from documents, blog posts, search results, logs, and tool output under an exact token, word, or character budget. Instead of keeping only text[:N], it can select complete fragments from across the source and reduce obvious repetition.

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.

When no question is available, it supports queryless mode which uses bounded structural trimming for readable source coverage.

Getting started

Installation

Trimwise supports Python 3.10 through 3.14.

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 for callbacks, model loading, concurrency, and GPU details.

Basic usage

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
print(result.spans)  # Original-input Python-string offsets

Many sources, one shared limit

Use trim_context() when passages from several sources should compete for one budget. Add ContextSource wrapper text when source labels or closing delimiters must fit inside that same limit:

from trimwise import ContextSource, Trimmer

result = Trimmer().trim_context(
    [
        ContextSource(
            text=record["text"],
            prefix=f"--- Source: {record['title']} ({record['url']}) ---\n",
            suffix="\n--- End source ---",
        )
        for record in records
    ],
    limit=800,
    query="Which recommendations are supported by the reports?",
    separator="\n\n",
)

prompt_ready_context = result.text
assert result.output_count <= result.limit

The result keeps one row per input source, including empty excerpts. A source's prefix and suffix are emitted together only when that source contributes evidence, and result.text contains the fully measured rendering. Your surrounding instructions and answer space remain outside this limit. Plain string sources still use the original evidence-only accounting. See Many Sources, One Shared Limit for both modes and the difference from atrim_many().

Depending on the trimming strategy you want to use, find the corresponding starter code example - auto, structural, lexical, semantic and hyrbid.

Available trimming strategies

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 for examples, scoring behavior, and practical tradeoffs.

How Trimwise compares with prompt compressors

Trimwise and model-based prompt compressors shorten text at different levels. Trimwise chooses complete source fragments before prompt assembly. Methods such as LLMLingua can remove individual tokens from an already assembled prompt, which can achieve much denser compression but may leave text that is harder for people to read or trace.

The LLMLingua family can preserve more task-relevant information per token at aggressive ratios. Its remaining tokens still come from the prompt, but complete sentence and block boundaries are not preserved. RECOMP's extractive path keeps selected sentences; its abstractive path can combine information across documents but no longer returns only original wording.

Choose Trimwise when evidence must stay readable, source fragments must remain verbatim and ordered, or adding another compression model is undesirable. Choose a model-based compressor when maximum compression density is more important and you can evaluate its effect on your own downstream task. The methods can also be chained: select broad evidence with Trimwise, then apply token-level compression. After the second step, Trimwise's whole-fragment and source-layout guarantees no longer describe the final prompt.

See the detailed research comparison for the differences among LLMLingua, LongLLMLingua, LLMLingua-2, Selective Context, and RECOMP.

Query-aware benchmark results

On a position-controlled 160-case benchmark, each method received the same source and question. The primary result is normalized contiguous required-span containment: every annotated source span must occur as one contiguous normalized passage, prohibited text must be absent, and the output must fit the budget. Trimwise Lexical leads at 128 tokens; Trimwise Hybrid leads from 256 through 1,024 tokens against the evaluated adapters.

The local ordered 80% and 90% sensitivity checks preserve the same ordering at every budget. This is a post-hoc robustness analysis over frozen outputs: it measures complete source-span survival, not semantic sufficiency, generated-answer quality, or every configuration in the compared method families. Latency is hardware-specific and excludes cold loading and thermal cooldown. The strict metric protocol, frozen manifest, and full sensitivity summary record the metric, inputs, and all results. The legacy bag-of-token case-pass result remains available as a historical diagnostic. The local benchmark environment resolves the published 0.2.0 release from PyPI.

An exploratory component study keeps Hybrid fixed while removing MMR, the adaptive evidence cutoff, or Markdown-aware segments. On this suite, the cutoff and structural segments help at 128 tokens; MMR shows no consistent strict-retention benefit. The full protocol, uncertainty intervals, and limits are in the benchmark documentation.

Documentation

• Getting Started
• Many Sources, One Shared Limit
• Strategies
• Semantic Models and Async Use
• Configuration and API
• How Trimwise Works
• Guarantees and Limitations
• Research Foundations
• API Reference

Trimwise is available under the MIT License and maintained by AATBIT Labs.