{"_id":"@axiomantic/llmlingua-2","_rev":"2-156ddee819e3a741bc06d1d74b6919e2","name":"@axiomantic/llmlingua-2","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@axiomantic/llmlingua-2","version":"0.1.0","keywords":["llmlingua","llmlingua-2","prompt-compression","transformers","huggingface","onnx","nlp"],"license":"MIT","_id":"@axiomantic/llmlingua-2@0.1.0","maintainers":[{"name":"elijahr","email":"elijahr+npm@gmail.com"}],"homepage":"https://github.com/axiomantic/llmlingua-2#readme","bugs":{"url":"https://github.com/axiomantic/llmlingua-2/issues"},"dist":{"shasum":"ee5b3dc43400af265d2fd7ce89cfe89a12f6bfed","tarball":"https://registry.npmjs.org/@axiomantic/llmlingua-2/-/llmlingua-2-0.1.0.tgz","fileCount":10,"integrity":"sha512-hF+WRvbpyes5tR4KupLghm7SenJRIVqk05ve7MnQnODXyj729H5dvYB3LKzULYrrcKEEhQlDp89wS7yDf1WsNQ==","signatures":[{"sig":"MEUCIQDbTtIXe9Glz9ad5y9hjuedWq4jGRz1h4M3S4PLYZ/2DQIgMxeIUyXivjCn1il+q2QhhikP13QDcim85ifZanjZ5l8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@axiomantic%2fllmlingua-2@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":107564},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"7084ba7a504af3fe4abd132b56ec4f059236c140","scripts":{"fmt":"biome check --write .","lint":"biome check .","test":"vitest run","build":"npm run gen:version && tsup","typecheck":"tsc --noEmit","gen:version":"node scripts/gen-version.mjs","prepublishOnly":"npm run lint && npm run typecheck && npm test && npm run build","test:integration":"LLMLINGUA_INTEGRATION=1 vitest run tests/integration.test.ts"},"_npmUser":{"name":"elijahr","email":"elijahr+npm@gmail.com"},"repository":{"url":"git+https://github.com/axiomantic/llmlingua-2.git","type":"git"},"_npmVersion":"10.8.2","description":"A TypeScript port of LLMLingua-2 prompt compression for Node.","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","vitest":"^4.0.0","typescript":"^6.0.3","@types/node":"^25.9.1","@biomejs/biome":"^2.4.15","@huggingface/transformers":"^4.0.0"},"peerDependencies":{"@huggingface/transformers":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/llmlingua-2_0.1.0_1779314793153_0.7792491404911965","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@axiomantic/llmlingua-2","version":"0.1.1","description":"A TypeScript port of LLMLingua-2 prompt compression for Node.","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"engines":{"node":">=20"},"publishConfig":{"access":"public","provenance":true},"scripts":{"gen:version":"node scripts/gen-version.mjs","build":"npm run gen:version && tsup","typecheck":"tsc --noEmit","lint":"biome check .","fmt":"biome check --write .","test":"vitest run","test:integration":"LLMLINGUA_INTEGRATION=1 vitest run tests/integration.test.ts","prepublishOnly":"npm run lint && npm run typecheck && npm test && npm run build"},"peerDependencies":{"@huggingface/transformers":"^4.0.0"},"devDependencies":{"@biomejs/biome":"^2.4.15","@huggingface/transformers":"^4.0.0","@types/node":"^25.9.1","tsup":"^8.3.0","typescript":"^6.0.3","vitest":"^4.0.0"},"keywords":["llmlingua","llmlingua-2","prompt-compression","transformers","huggingface","onnx","nlp"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/axiomantic/llmlingua-2.git"},"bugs":{"url":"https://github.com/axiomantic/llmlingua-2/issues"},"homepage":"https://github.com/axiomantic/llmlingua-2#readme","gitHead":"7402d0bc0ab8976a2faffb25cdfa3ca503d18467","_id":"@axiomantic/llmlingua-2@0.1.1","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-3xdezwELsf0JUNuHVWeaUoF1IsRJ9Hrhtl+iP6Olkfaq6OXVexlPiafafLPV3hRQBVV816NmZaRJSJ+0zNQ1tw==","shasum":"c4f8aaf856d8578e3b6089779f9099075b944997","tarball":"https://registry.npmjs.org/@axiomantic/llmlingua-2/-/llmlingua-2-0.1.1.tgz","fileCount":10,"unpackedSize":107837,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@axiomantic%2fllmlingua-2@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCZ37USdDv7KCz4uSONvQ3tmh7lmp8lohdUdK6gCgJbIgIhAIg+eiWSHBqnLV+Rfz9PE2oeADvpn4NcAelLyof3DX5f"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:5db2fbc5-4128-4061-b08a-eecd98ebaa48"}},"directories":{},"maintainers":[{"name":"elijahr","email":"elijahr+npm@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/llmlingua-2_0.1.1_1779317745874_0.276032502729755"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-20T22:06:32.947Z","modified":"2026-05-20T22:55:46.400Z","0.1.0":"2026-05-20T22:06:33.289Z","0.1.1":"2026-05-20T22:55:46.029Z"},"bugs":{"url":"https://github.com/axiomantic/llmlingua-2/issues"},"license":"MIT","homepage":"https://github.com/axiomantic/llmlingua-2#readme","keywords":["llmlingua","llmlingua-2","prompt-compression","transformers","huggingface","onnx","nlp"],"repository":{"type":"git","url":"git+https://github.com/axiomantic/llmlingua-2.git"},"description":"A TypeScript port of LLMLingua-2 prompt compression for Node.","maintainers":[{"name":"elijahr","email":"elijahr+npm@gmail.com"}],"readme":"# @axiomantic/llmlingua-2\n\n[![npm version](https://img.shields.io/npm/v/@axiomantic/llmlingua-2.svg)](https://www.npmjs.com/package/@axiomantic/llmlingua-2) [![npm downloads](https://img.shields.io/npm/dm/@axiomantic/llmlingua-2.svg)](https://www.npmjs.com/package/@axiomantic/llmlingua-2) [![CI](https://github.com/axiomantic/llmlingua-2/actions/workflows/ci.yml/badge.svg)](https://github.com/axiomantic/llmlingua-2/actions/workflows/ci.yml) [![License](https://img.shields.io/npm/l/@axiomantic/llmlingua-2.svg)](./LICENSE) [![Types](https://img.shields.io/npm/types/@axiomantic/llmlingua-2.svg)](https://www.npmjs.com/package/@axiomantic/llmlingua-2) [![Node](https://img.shields.io/node/v/@axiomantic/llmlingua-2.svg)](https://www.npmjs.com/package/@axiomantic/llmlingua-2)\n\nTyped [LLMLingua-2](https://llmlingua.com/) prompt compression for Node, via [`@huggingface/transformers`](https://github.com/huggingface/transformers.js).\n\nDual ESM + CJS. Node ≥20. MIT-licensed. Bring-your-own `@huggingface/transformers@^3` (peer dependency).\n\n## Install\n\n```sh\nnpm install @axiomantic/llmlingua-2 @huggingface/transformers\n```\n\n`@huggingface/transformers` is declared as a peer dependency. Pin the same major version your application uses; we develop against `^3`.\n\n## Quick start\n\n```ts\nimport lingua from \"@axiomantic/llmlingua-2\";\n\nconst text = \"Long meeting transcript or RAG context here...\";\nconst { compressed, reverseMap } = await lingua.compress(text, { targetRatio: 0.5 });\n\n// Hand `compressed` to your downstream LLM. Stash `reverseMap` only if you\n// need a faithful round-trip later (see \"Decompression semantics\").\nconst restored = await lingua.decompress(compressed, reverseMap);\nconsole.assert(restored === text);\n```\n\nThe default import is a lazy singleton: the constructor stores config only; the ONNX model is downloaded from the Hugging Face Hub on the first `compress` call. Subsequent calls reuse the same model in memory.\n\n## API reference\n\n### `LLMLingua2Wrapper`\n\n```ts\nclass LLMLingua2Wrapper implements LLMLinguaWrapper {\n  readonly modelId: string;\n  readonly version: string;\n  readonly available: boolean;\n  constructor(options?: WrapperOptions);\n  compress(text: string, opts?: CompressOptions):\n    Promise<{ compressed: string; reverseMap: unknown }>;\n  decompress(compressed: string, reverseMap: unknown): Promise<string>;\n}\n```\n\n### `WrapperOptions`\n\n| Field | Type | Default | Notes |\n|---|---|---|---|\n| `modelId` | `string` | `\"atjsh/llmlingua-2-js-xlm-roberta-large-meetingbank\"` | Hugging Face repo id. Empty / non-string throws `TypeError` at construction. |\n| `revision` | `string` | `undefined` | Recommended: pin to a specific commit hash. |\n| `quantized` | `boolean` | `true` | `true` maps to `dtype: 'q8'` (~560 MB); `false` maps to `dtype: 'fp32'` (~2.2 GB). |\n| `transformersOptions` | `Record<string, unknown>` | `{}` | Forwarded to `AutoTokenizer` / `AutoModelForTokenClassification` (e.g. `device`, `dtype`, `cache_dir`, `local_files_only`). Wins over `quantized`. |\n\n### `CompressOptions`\n\n| Field | Type | Default | Notes |\n|---|---|---|---|\n| `targetRatio` | `number` | `0.5` | Fraction of source tokens to retain. Clamped silently to `[0.05, 0.95]`. |\n\n### `CompressResult`\n\n```ts\ninterface CompressResult {\n  compressed: string;\n  reverseMap: unknown;   // opaque to consumers; pass back to decompress\n}\n```\n\n### Error hierarchy\n\n```ts\nclass LLMLingua2Error extends Error { readonly code: string }\nclass LLMLingua2NotAvailableError extends LLMLingua2Error    // code: \"ENOT_AVAILABLE\"\nclass LLMLingua2InvalidReverseMapError extends LLMLingua2Error  // code: \"EINVALID_REVERSE_MAP\"\n```\n\n| Condition | Surface | Error |\n|---|---|---|\n| Model load fails | `compress` rejects | `LLMLingua2NotAvailableError` (with `cause`) |\n| Malformed `reverseMap` | `decompress` rejects | `LLMLingua2InvalidReverseMapError` |\n| `text` not a string | `compress` throws sync | `TypeError` (caller bug) |\n| Empty input | `compress` returns `{ compressed: \"\", reverseMap: {…} }` | (no error) |\n\nCatch any library-originated error with `instanceof LLMLingua2Error`; switch on `.code` for stable identification.\n\n## Decompression semantics\n\nLLMLingua-2 is a **one-way lossy** compressor. The model predicts a per-token \"preserve\" probability and drops the lowest-scoring tokens; there is no learned decoder. To honor the `decompress(compressed, reverseMap) → original` contract, this library stashes the original text inside the `reverseMap` payload so `decompress` is a faithful round-trip.\n\nPractical consequences:\n\n- `decompress` does **not** load the model. It just reads `reverseMap.originalText`. You can call it without ever paying the model-download cost.\n- If you don't need round-trip (you're only sending `compressed` to a downstream LLM), discard `reverseMap` immediately to free memory.\n- `reverseMap` is JSON-serializable. You can persist it to disk or send it over the wire and `decompress` later in a different process.\n- The name `decompress` is dictated by the pinned interface contract, not by the model's actual capabilities. This is documented behavior, not a bug.\n\n## Model provenance\n\nThe default model is [`atjsh/llmlingua-2-js-xlm-roberta-large-meetingbank`](https://huggingface.co/atjsh/llmlingua-2-js-xlm-roberta-large-meetingbank) on the Hugging Face Hub: an ONNX export (int8 + fp32 variants) of Microsoft Research's [LLMLingua-2](https://github.com/microsoft/LLMLingua) trained on the MeetingBank dataset.\n\nWe strongly recommend pinning `revision` to a specific commit hash in production. The default behavior (no pin) follows the Hub's `main` branch and is subject to upstream changes.\n\nA future minor release may re-host the ONNX weights under the `axiomantic/` namespace for supply-chain durability; the default `modelId` will change in a clearly-documented major or minor bump if it does.\n\n## Limitations (v0.1)\n\n- **English-biased sentence chunking.** The chunker splits on `.`, `!`, `?` followed by whitespace. CJK, Arabic, and other non-whitespace scripts may collapse into a single chunk and exceed the 512-token limit; transformers.js then truncates. The full original text remains accessible via `reverseMap.originalText` so `decompress` round-trips correctly.\n- **No streaming compress.** `compress` accumulates per-chunk output into a single string.\n- **`available` is a snapshot.** Reading `wrapper.available` immediately after construction returns `false`; await the first `compress` call to ensure the model is ready, or poll `available` after dispatching one compress.\n- **No browser / WebGPU support in v0.1.** Designed for Node ≥20.\n- **Integration test not on PR CI.** Real model load downloads ~560 MB; run `npm run test:integration` locally with `LLMLINGUA_INTEGRATION=1`. The same suite runs nightly (Mondays 07:00 UTC) and on `workflow_dispatch` via `.github/workflows/integration.yml`.\n\n## CJS usage\n\nThis package ships both ESM (`dist/index.js`) and CJS (`dist/index.cjs`)\nbuilds; Node's exports resolution selects the right one automatically.\n\n```js\n// CommonJS\nconst lingua = require(\"@axiomantic/llmlingua-2\").default;\nconst out = await lingua.compress(\"...\");\n\n// or from an ESM-only consumer\nconst lingua = (await import(\"@axiomantic/llmlingua-2\")).default;\n```\n\n## Contributing\n\nSource: [github.com/axiomantic/llmlingua-2](https://github.com/axiomantic/llmlingua-2).\n\nTo re-export the ONNX model from a PyTorch checkpoint, see `scripts/convert.sh` (operator-runnable; not exercised in CI).\n\n```sh\nnpm install\nnpm test            # unit tests, mocked transformers\nnpm run typecheck\nnpm run build\nnpm run test:integration   # downloads ~560 MB; opt-in\n```\n\n## Prior art\n\n[`@atjsh/llmlingua-2`](https://www.npmjs.com/package/@atjsh/llmlingua-2) ([repo](https://github.com/atjsh/llmlingua-2-js)) is an earlier JavaScript/TypeScript implementation of LLMLingua-2 by the same author who produced the ONNX export this package consumes. If you want a more direct port with a different API surface, consider it.\n\nThis package is an independent implementation focused on a pinned `LLMLinguaWrapper` contract, dual ESM/CJS distribution, Sigstore provenance, and integration tests that assert against real model output.\n\n## License & attribution\n\nMIT. Copyright (c) 2026 Axiomantic. See [LICENSE](./LICENSE).\n\nThis package wraps [Microsoft LLMLingua-2](https://github.com/microsoft/LLMLingua) (MIT) and the [atjsh ONNX export](https://huggingface.co/atjsh/llmlingua-2-js-xlm-roberta-large-meetingbank) (see upstream for terms).\n\n## Citation\n\nIf you use this library in academic work, please cite the underlying LLMLingua-2 paper:\n\n```bibtex\n@inproceedings{pan-etal-2024-llmlingua,\n    title = \"{LLML}ingua-2: Data Distillation for Efficient and Faithful Task-Agnostic Prompt Compression\",\n    author = \"Pan, Zhuoshi and\n      Wu, Qianhui and\n      Jiang, Huiqiang and\n      Xia, Menglin and\n      Luo, Xufang and\n      Zhang, Jue and\n      Lin, Qingwei and\n      R{\\\"u}hle, Victor and\n      Yang, Yuqing and\n      Lin, Chin-Yew and\n      Zhao, H. Vicky and\n      Qiu, Lili and\n      Zhang, Dongmei\",\n    editor = \"Ku, Lun-Wei and\n      Martins, Andr{\\'e} and\n      Srikumar, Vivek\",\n    booktitle = \"Findings of the Association for Computational Linguistics: {ACL} 2024\",\n    month = aug,\n    year = \"2024\",\n    address = \"Bangkok, Thailand and virtual meeting\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https://aclanthology.org/2024.findings-acl.57\",\n    doi = \"10.18653/v1/2024.findings-acl.57\",\n    pages = \"963--981\",\n}\n```\n","readmeFilename":"README.md"}