{
  "markdown": "# CompactPrompt\n\n[![Tests](https://github.com/gtkcyber/compact_prompt/actions/workflows/tests.yml/badge.svg)](https://github.com/gtkcyber/compact_prompt/actions/workflows/tests.yml)\n[![Pylint](https://github.com/gtkcyber/compact_prompt/actions/workflows/pylint.yml/badge.svg)](https://github.com/gtkcyber/compact_prompt/actions/workflows/pylint.yml)\n[![Documentation Status](https://readthedocs.org/projects/compact-prompt/badge/?version=latest)](https://compact-prompt.readthedocs.io/en/latest/)\n![PyPI - Version](https://img.shields.io/pypi/v/compactprompt)\n[![gtkcyber/compact_prompt MCP server](https://glama.ai/mcp/servers/gtkcyber/compact_prompt/badges/score.svg)](https://glama.ai/mcp/servers/gtkcyber/compact_prompt)\n\n\nCompactPrompt shortens the text you send to an AI model while preserving its\nmeaning. The result costs less to run, returns faster, and is less likely to\nexceed the model's input limit. The common case is a single function call, and\nno background in machine learning is required to use it.\n\n## Background\n\nAn AI model reads an input — the *prompt* — and returns a response. Providers\ncharge according to the amount of text processed, measured in *tokens* (each\ntoken is roughly three-quarters of a word), and every model has a maximum input\nsize. A long prompt that combines instructions, documents, tables, and examples\ntherefore costs more, responds more slowly, and may not fit at all.\n\nCompactPrompt reduces the size of a prompt while retaining the information that\nmatters, so you keep the substance and discard the overhead.\n\n## Getting started\n\nInstall the library:\n\n```bash\npip install compactprompt\n```\n\nShorten a prompt:\n\n```python\nfrom compactprompt import CompactPrompt\n\nresult = CompactPrompt.compact(\n    \"Please could you very kindly go ahead and provide a really concise \"\n    \"summary of the quarterly report.\"\n)\n\nprint(result.text)\nprint(f\"{result.ratio:.1f}x smaller \"\n      f\"({result.tokens_before} -> {result.tokens_after} tokens)\")\n```\n\nOutput:\n\n```\na really concise summary of the quarterly report.\n1.7x smaller (22 -> 13 tokens)\n```\n\nThe filler — *\"Please could you very kindly go ahead and\"* — is removed, and the\nmeaning is unchanged.\n\n## What it does\n\nCompactPrompt provides several methods for reducing the size of a prompt. They\ncan be used individually or together. Each is described below in plain terms,\nfollowed by an optional technical note.\n\n### Trimming low-value wording\n\nRemoves words that carry little meaning, such as conversational filler, and\nkeeps the words that do. This is lossy: the removed words are not recoverable,\nbut the result is ready to use as it is.\n\n```python\nfrom compactprompt import CompactPrompt\n\n# Remove approximately 40% of the tokens\nresult = CompactPrompt.compact(prompt, ratio=0.4)\n\n# Or target a specific size\nresult = CompactPrompt.compact(prompt, budget=64)\n```\n\n<details>\n<summary>Technical detail</summary>\n\nEach word receives an information score that combines how rare it is in general\n(static self-information) with how predictable it is in context (dynamic\nself-information from a small language model). Low-scoring words are removed.\nWhole grammatical phrases are removed together, using spaCy, so the result\nremains readable, and names and numbers are protected. This implements the\nfusion rule from the *CompactPrompt* paper.\n</details>\n\n### Reversible shortening of repeated phrases\n\nWhen a phrase recurs, it is replaced with a short placeholder, and a key records\nwhat each placeholder stands for. This is lossless: the exact original can be\nrestored at any time.\n\n```python\nimport compactprompt as cp\n\ndoc = \"operating cash flow rose. operating cash flow fell. operating cash flow held.\"\nabbr = cp.abbreviate(doc, n=3)\n\nprint(abbr.text)        # '@0 rose. @0 fell. @0 held.'\nprint(abbr.dictionary)  # {'@0': 'operating cash flow'}\nprint(abbr.restore())   # the exact original\n```\n\nRetain `abbr.dictionary` so the placeholders can be expanded again later.\n\n### Reducing the size of numeric data\n\nLarge tables of numbers consume many tokens. This lowers their precision to save\nspace while guaranteeing that the rounding never exceeds a known bound.\n\n```python\nimport compactprompt as cp\n\nq = cp.quantize([1.0, 2.5, 3.3, 4.8, 9.2, 10.0], bits=8)\nq.reconstruct()   # the rounded values\nq.max_error       # the guaranteed maximum error\n```\n\n### Selecting representative examples\n\nModels perform better when shown a few examples. If you have many candidate\nexamples, this selects a small, varied subset that still reflects the full\nrange, so you send a representative few rather than all of them.\n\n```python\nfrom compactprompt import select_examples\n\nchosen = select_examples(my_examples)\nchosen.examples\n```\n\n## Choosing how the wording is trimmed\n\nThe wording-trimming step can be carried out by any of three interchangeable\nengines. All of them shorten text; they differ in how they decide what to remove\nand in what they require to run. Select one with the `engine` argument — nothing\nelse in your code changes.\n\n| Engine | Approach | Requirements |\n|--------|----------|--------------|\n| **Built-in** (default) | Scores each word and removes the least useful. Runs locally. | None |\n| **LLMLingua** | Microsoft's established tool, which uses a small model to decide what to remove. | Downloads a model |\n| **Caveman** | Rewrites the text in a concise style, preserving code, links, and headings. | Access to a language model |\n\n```python\nCompactPrompt.compact(prompt)                       # built-in, no extra install\nCompactPrompt.compact(prompt, engine=\"llmlingua\")   # pip install 'compactprompt[llmlingua]'\nCompactPrompt.compact(prompt, engine=\"caveman\")     # pip install 'compactprompt[caveman]'\n```\n\nThe built-in engine and the other core features implement the\n[*CompactPrompt* research paper](https://arxiv.org/abs/2510.18043). LLMLingua and\nCaveman are independent open-source tools that this library integrates; see\n[Attribution](#attribution).\n\n## Compacting files and skills\n\nCompactPrompt can also compact whole markdown files — documentation,\n`CLAUDE.md`, notes, and Claude Code **skills** (`SKILL.md`) — not just strings.\nIt can first **review** a file or folder to report where the savings are.\n\nThis works safely by design: YAML frontmatter is preserved exactly, fenced code\nblocks and links are never altered, the result is rejected if it would change a\nheading, code block, or URL, and nothing is written without `--apply` (which\nfirst saves a `.bak` backup). Files that look like code, config, or secrets are\nskipped automatically.\n\nFrom the command line:\n\n```bash\n# See where the savings are (read-only)\ncompactprompt review ./skills\n\n# Preview the compaction of one skill (writes nothing)\ncompactprompt compact ./skills/my-skill/SKILL.md --engine builtin\n\n# Apply it (saves SKILL.md.bak, then rewrites the file)\ncompactprompt compact ./skills/my-skill/SKILL.md --engine caveman --apply\n```\n\n`--engine` is required — you choose `builtin`, `llmlingua`, or `caveman` each\ntime (caveman, which rewrites prose, is usually best for human-readable files).\n\nFrom Python:\n\n```python\nfrom compactprompt import review_file, compact_file\n\nreport = review_file(\"SKILL.md\")\nprint(report.tokens, report.issues)\n\nresult = compact_file(\"SKILL.md\", engine=\"caveman\", apply=True)\nprint(result.tokens_before, \"->\", result.tokens_after)\n```\n\nThe Streamlit app's **Files & Skills** tab does the same interactively.\n\n## Optional features\n\nThe basic installation requires no setup. Additional features depend on extra\ncomponents, which you install only as needed:\n\n```bash\npip install compactprompt                  # core: trimming and reversible shortening\npip install 'compactprompt[ml]'            # numeric reduction and example selection\npip install 'compactprompt[llmlingua]'     # the LLMLingua engine\npip install 'compactprompt[caveman]'       # the Caveman engine\npip install 'compactprompt[mcp]'           # the MCP server for AI agents\npip install 'compactprompt[app]'           # the interactive application\npip install 'compactprompt[all]'           # everything\n```\n\nWhen a feature needs a component that is not installed, CompactPrompt reports\nexactly what to install.\n\n## Interactive application\n\nA small web application lets you paste a prompt and see it shortened, with the\nsavings reported as you go:\n\n```bash\npip install 'compactprompt[app]'\nstreamlit run compactprompt_app.py\n```\n\nIt opens in the browser. Use the sidebar to choose an engine and set how much to\nremove.\n\n## Use it from an AI agent\n\nCompactPrompt ships an **MCP server** so AI coding tools (Claude Code, Codex,\nCursor, Gemini, and any MCP-capable agent) can review and compact prompts, docs,\nand skills directly:\n\n```bash\npip install 'compactprompt[mcp]'      # provides the `compactprompt-mcp` command\nclaude mcp add compactprompt -- compactprompt-mcp   # e.g. for Claude Code\n```\n\nThe [`agent-skills/`](agent-skills/) directory also has lightweight skill/rules\nfiles and an `install.sh` for the same tools. See its\n[README](agent-skills/README.md) for per-tool configuration.\n\n<!-- mcp-name: io.github.gtkcyber/compactprompt -->\n\n## Confirming the meaning is preserved\n\nTo check that a shortened prompt still means the same thing, you can measure the\nsimilarity between the original and the result, where 1.0 indicates identical\nmeaning:\n\n```python\nfrom compactprompt import cosine_fidelity   # pip install 'compactprompt[embeddings]'\n\nscore = cosine_fidelity(original_text, result.text)\nprint(score.mean)\n```\n\n## Reference\n\n`CompactPrompt.compact(...)` returns a result object with the following fields:\n\n| Field | Meaning |\n|-------|---------|\n| `.text` | The shortened prompt. |\n| `.original` | The input. |\n| `.tokens_before` / `.tokens_after` | Size before and after. |\n| `.ratio` | How many times smaller (for example, `2.3`). |\n| `.savings` | Fraction of tokens saved (for example, `0.4`). |\n| `.dictionary` | The key for restoring shortened phrases, when used. |\n| `.restore()` | Reverses the reversible shortening step. |\n\nThe principal options:\n\n```python\nCompactPrompt.compact(\n    prompt,\n    ratio=0.5,          # how much to remove: 0.5 targets about half the tokens\n    budget=None,        # alternatively, a specific target token count\n    prune=True,         # trim the wording (default)\n    abbreviate=False,   # also shorten repeated phrases (reversible)\n    engine=\"builtin\",   # \"builtin\", \"llmlingua\", or \"caveman\"\n)\n```\n\nThe complete reference, including the advanced options, is in the\n[documentation](https://compact-prompt.readthedocs.io/).\n\n## Development\n\nRun the tests:\n\n```bash\npip install pytest\npytest\n```\n\nThe suite runs against the dependency-free core; tests for optional features are\nskipped automatically when those components are absent.\n\nBuild the documentation locally:\n\n```bash\npip install 'compactprompt[docs]'\nmkdocs serve\n```\n\n## Citation\n\nThis library implements the methodology from:\n\n```bibtex\n@article{choi2025compactprompt,\n  title={CompactPrompt: A Unified Pipeline for Prompt and Data Compression in LLM Workflows},\n  author={Choi, Joong Ho and Zhao, Jiayang and Shah, Jeel and Sonawane, Ritvika and\n          Singh, Vedant and Appalla, Avani and Flanagan, Will and Condessa, Filipe},\n  journal={arXiv preprint arXiv:2510.18043},\n  year={2025}\n}\n```\n\nIt is an independent implementation and is not affiliated with the authors of\nthe paper.\n\n## Attribution\n\nThe Caveman engine (`compactprompt/caveman.py`) is adapted from\n[Caveman](https://github.com/JuliusBrussee/caveman) by Julius Brussee (MIT). The\nLLMLingua engine uses [LLMLingua](https://github.com/microsoft/LLMLingua) by\nMicrosoft (MIT). Full third-party attributions and license notices are in\n[`THIRD_PARTY_NOTICES.md`](https://github.com/gtkcyber/compact_prompt/blob/main/THIRD_PARTY_NOTICES.md).\n",
  "bytes": 11808,
  "sha": "4603ec1d57d64e059dc685316fbea94a8b7821c2f51daa9c221d7a67c5798e19",
  "repo_slug": "gtkcyber/compact_prompt",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gtkcyber_compactprompt_1aac486f/readme"
}