# FreeLLMAPI Prompt Compression Modes: A Complete Guide to `off`, `lossless`, `standard`, and `aggressive`

> Explore FreeLLMAPI prompt compression modes: off, lossless, standard, and aggressive. Learn how to optimize your LLM prompts for better performance and efficiency.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: deep-dive
- Published: 2026-08-28

---

**FreeLLMAPI supports four distinct prompt compression modes—`off`, `lossless`, `standard`, and `aggressive`—that control how incoming chat prompts are reduced before being sent to a language model.**

The server codebase implements these modes in a dedicated compression service, allowing developers to optimize token usage based on their fidelity requirements. This article explores how each mode works, when to use them, and how to configure them via the API.

## What Are Prompt Compression Modes?

Prompt compression modes determine how aggressively FreeLLMAPI reduces the token count of incoming prompts. In [`server/src/services/compression/types.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/types.ts), the `COMPRESSION_MODES` constant defines the four available options, and the `CompressionMode` type is derived from this array. The pipeline in [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) then selects appropriate compression engines based on your chosen mode.

## The Four Compression Modes

### `off` — No Compression

The `off` mode forwards prompts unchanged. Use this for debugging or when your provider handles compression internally.

Characteristics:
- Zero token reduction
- Full semantic preservation
- Useful for inspecting raw requests

### `lossless` — Conservative Reductions

`lossless` applies transformations that never alter semantic content, such as removing redundant whitespace and deduplicating identical messages.

Characteristics:
- Minor token savings
- Guaranteed semantic equivalence
- Ideal when every token matters but some inefficiency exists

### `standard` — Balanced Optimization

`standard` combines lossy and lossless transformations to reduce token count while retaining overall meaning. This is the recommended default for most production workloads.

Characteristics:
- Good token savings with minimal fidelity loss
- Balanced engine selection
- General-purpose compression for most models

### `aggressive` — Maximum Reduction

`aggressive` enables the most intensive optimizations, including aggressive JSON compacting and tool-result filtering. Use this when strict token limits apply.

Characteristics:
- Maximum token reduction
- Potentially lossy transformations
- Best for models that tolerate approximation

## How to Configure Compression Modes

### Update Settings via API

Configure the active mode through the compression settings endpoint:

```typescript
// Example using fetch to update the compression configuration
await fetch('https://your-free-llmapi-instance.com/api/settings/compression', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'standard',               // Choose one of: off | lossless | standard | aggressive
    engines: {                     // Engine-specific options (optional)
      jsoncompact: { enabled: true },
    },
    trustProjectFilters: true,
    prefixFreeze: false,
  }),
});

```

The `mode` field accepts any `CompressionMode` value. Optional `engines` configuration allows fine-tuning specific compression engines per mode.

### Preview Compression Results

Test how a prompt compresses under different modes before applying them:

```typescript
const response = await fetch('https://your-free-llmapi-instance.com/api/compression/preview', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    header: 'User',
    tools: [{ name: 'search', description: 'Web search', parameters: {} }],
    messages: [
      { role: 'user', content: 'Explain quantum entanglement in simple terms.' },
    ],
    previewMode: 'aggressive',   // Try any of the four modes
  }),
});
const { messages, stats } = await response.json();
console.log('Compressed prompt:', messages);
console.log('Compression stats:', stats);

```

The preview endpoint returns both the compressed messages and statistics about the reduction achieved.

### Inspect Current Configuration

Retrieve the active compression settings:

```typescript
const { mode, engines } = await (await fetch('/api/settings/compression')).json();
console.log(`Current mode: ${mode}`);
console.log('Engine options:', engines);

```

This queries [`server/src/routes/compression.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/compression.ts), which interfaces with [`server/src/services/compression/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/config.ts) for configuration management.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`server/src/services/compression/types.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/types.ts) | Defines `COMPRESSION_MODES` and `CompressionMode` type |
| [`server/src/services/compression/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/config.ts) | Parses, validates, and stores compression configuration |
| [`server/src/routes/compression.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/compression.ts) | API routes for settings and preview endpoints |
| [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) | Core pipeline applying engines based on selected mode |
| [`server/docs/compression.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/docs/compression.md) | Extended documentation on mode behavior |

## Summary

- **Four modes available**: `off`, `lossless`, `standard`, and `aggressive`, defined in [`server/src/services/compression/types.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/types.ts)
- **Progressive trade-offs**: From zero compression (`off`) to maximum reduction (`aggressive`)
- **API-configurable**: Set via `PUT /api/settings/compression` with optional engine-specific tuning
- **Preview before applying**: Use `POST /api/compression/preview` to test compression results
- **Pipeline-driven**: [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) orchestrates engine selection based on mode

## Frequently Asked Questions

### What is the default compression mode in FreeLLMAPI?

The default mode depends on your initial configuration. Check the current setting via `GET /api/settings/compression` against [`server/src/services/compression/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/config.ts). Most deployments start with `standard` as the balanced default.

### Can I use different compression modes for different API endpoints?

Yes. Mode selection is request-scoped through the preview endpoint, or you can implement middleware that dynamically swaps configurations via the settings API before forwarding requests.

### Does aggressive compression affect function calling or tool results?

Potentially. The `aggressive` mode may apply tool-result filtering and aggressive JSON compacting. Test thoroughly with [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) debug logging if your application relies heavily on structured tool outputs.

### How do I disable compression entirely for debugging?

Set `mode: 'off'` via the settings endpoint. This bypasses all compression engines in [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) and forwards prompts unchanged.