|
| 1 | +# vecr-compress |
| 2 | + |
| 3 | +[vecr-compress](https://github.com/h2cker/vecr) is an open-source LLM context compressor with a deterministic retention contract. It pins structured tokens — order IDs, dates, URLs, emails, code references — via an auditable regex whitelist before running token-budget packing. Filler phrases are hard-dropped; remaining sentences are ranked by question-aware Jaccard scoring. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +| Property | Value | |
| 8 | +|---|---| |
| 9 | +| Package | `langchain-vecr-compress` | |
| 10 | +| License | Apache 2.0 | |
| 11 | +| Python | 3.10+ | |
| 12 | +| Retention contract | Deterministic (regex whitelist, 13 built-in rules) | |
| 13 | +| Streaming | No (one-shot, synchronous) | |
| 14 | + |
| 15 | +## Installation |
| 16 | + |
| 17 | +```bash |
| 18 | +pip install langchain-vecr-compress |
| 19 | +``` |
| 20 | + |
| 21 | +## Usage |
| 22 | + |
| 23 | +```python |
| 24 | +from langchain_core.messages import AIMessage, HumanMessage, SystemMessage |
| 25 | +from langchain_vecr_compress import VecrContextCompressor |
| 26 | + |
| 27 | +compressor = VecrContextCompressor(budget_tokens=2000) |
| 28 | + |
| 29 | +compressed = compressor.compress_messages([ |
| 30 | + SystemMessage(content="You are a refund analyst."), |
| 31 | + HumanMessage(content="Order ORD-99172 placed 2026-03-15. Amount $1,499.00."), |
| 32 | + HumanMessage(content="What is the refund status?"), |
| 33 | +]) |
| 34 | +``` |
| 35 | + |
| 36 | +`AIMessage` objects with `tool_calls` are preserved verbatim and round-trip intact. |
| 37 | + |
| 38 | +## Advanced usage |
| 39 | + |
| 40 | +Access the full compression report for telemetry: |
| 41 | + |
| 42 | +```python |
| 43 | +result = compressor.compress_with_report(messages) |
| 44 | +print(f"Ratio: {result.ratio:.1%}, pinned facts: {len(result.retained_matches)}") |
| 45 | +``` |
| 46 | + |
| 47 | +Add custom retention rules for domain-specific identifiers: |
| 48 | + |
| 49 | +```python |
| 50 | +import re |
| 51 | +from vecr_compress import RetentionRule, DEFAULT_RULES |
| 52 | + |
| 53 | +rules = DEFAULT_RULES.with_extra([ |
| 54 | + RetentionRule(name="ticket", pattern=re.compile(r"\bTICKET-\d{4,8}\b")), |
| 55 | +]) |
| 56 | +compressor = VecrContextCompressor(budget_tokens=2000, retention_rules=rules) |
| 57 | +``` |
| 58 | + |
| 59 | +## API reference |
| 60 | + |
| 61 | +See the [vecr-compress GitHub repo](https://github.com/h2cker/vecr) for full API docs, the retention contract specification ([RETENTION.md](https://github.com/h2cker/vecr/blob/main/RETENTION.md)), and changelog. |
0 commit comments