@codragraph/compress

@codragraph/compress

Lossless semantic compression for LLM context, including CodraGraph FeatureCluster context packs.

Use this package when the agent already has the right context pack but the pack is too large for a prompt budget. @codragraph/compress keeps the facts that matter for editing code: files, line ranges, symbols, routes, tools, processes, dependencies, tests, docs, and safe-edit warnings.

Install

npm install @codragraph/compress

Basic Usage

import { LlmCompressor, compressContextPack } from "@codragraph/compress";
import { harness, graph } from "@codragraph/sdk";

const inference = await harness.makeInferenceProvider("openai");
const graphClient = await graph.createLocalGraphClient();
const settingsPack = await graphClient.contextPack({ name: "Settings" });

const compressor = new LlmCompressor();
const compressed = await compressContextPack(compressor, settingsPack, {
  inference,
  level: "balanced",
  format: "outline",
});

console.log(compressed.clusterName);
console.log(compressed.reduction);
console.log(compressed.compressed);

What It Compresses

flowchart LR
    Pack["FeatureCluster context pack"] --> Outline["Stable outline or JSON"]
    Outline --> LLM["LlmCompressor"]
    LLM --> Prompt["Smaller agent prompt"]

compressContextPack accepts a ClusterContextPack from @codragraph/shared or any compatible object. The helper first serializes the pack deterministically, then passes it to a Compressor.

Public API

Export	Purpose
LlmCompressor	LLM-backed compressor/decompressor.
compressContextPack	Compress a FeatureCluster context pack as outline or JSON.
estimateTokens	Lightweight character-based token estimate.
Compressor	Interface for custom compressors.
CompressOptions	Inference provider, model, level, strategy, similarity options.
CompressContextPackOptions	CompressOptions plus `format: "outline"

Package Composition

Pair with	Why
@codragraph/cli	Produces the indexed graph and FeatureCluster packs.
@codragraph/sdk	Loads context packs programmatically.
@codragraph/harness	Supplies inference providers and can use compressed packs in tuned recipes.

Notes

• This is prompt/context compression, not storage compression. Storage compression is the CLI flag codragraph analyze --compress brotli|zstd.
• The package is TypeScript/Node-first. Older Python experiments live outside the public npm surface.

License

Apache-2.0. You can use, modify, redistribute, bundle, and host this package commercially, subject to the Apache-2.0 notice and attribution requirements.