Compress Light Reach

OpenAI-compatible LLM routing + compression SDK (superset responses with LightReach metadata)

Compress Light Reach is a Node.js/TypeScript SDK that provides intelligent model routing and prompt compression for LLM applications, reducing token usage and costs while maintaining quality.

Features

• Intelligent Model Routing: Automatically selects the optimal model based on admin-configured quality settings and available provider keys
• Token-aware Compression: Replaces repeated substrings with shorter placeholders using a fast greedy algorithm
• Lossless Input Compression: Prompt reconstruction is deterministic
• Cloud API: Uses Light Reach's cloud service for compression and routing
• Multi-provider Support: OpenAI, Anthropic, Google, DeepSeek, Moonshot
• TypeScript: Full TypeScript support with type definitions
• BYOK: Provider API keys managed securely in dashboard (never passed through SDK)

Installation

npm install compress-lightreach

or

yarn add compress-lightreach

Quick Start

The SDK uses intelligent model routing and targets POST /api/v2/complete.

• Authenticate with your LightReach API key (env var PCOMPRESLR_API_KEY or LIGHTREACH_API_KEY)
• Manage provider keys (OpenAI/Anthropic/Google/etc.) in the dashboard (BYOK)
• System automatically selects the optimal model based on admin-configured quality settings

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const result = await client.complete({
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in simple terms.' },
  ],
  tags: { team: 'backend', environment: 'production' },
});

console.log(result.choices[0].message.content);
console.log(`Selected: ${result.routing_info?.selected_model}`);
console.log(`Token savings: ${result.compression_stats.token_savings}`);

OpenAI-compatible API (Cursor / OpenAI SDKs)

LightReach also exposes a strict OpenAI-compatible surface (including streaming SSE) so you can use standard OpenAI tooling without changing your app.

• Cursor base URL: https://api.compress.lightreach.io/v1/cursor
• Generic OpenAI-compatible base URL: https://api.compress.lightreach.io/v1
• Endpoints: GET /models, POST /chat/completions
• Model id: lightreach

Example (cURL):

curl -sS https://api.compress.lightreach.io/v1/chat/completions \
  -H "Authorization: Bearer lr_your_lightreach_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lightreach",
    "messages": [{"role":"user","content":"Say hello"}],
    "stream": true
  }'

Tags

Tags provide cost attribution and enable admin-controlled quality ceilings per tag. The system supports three tag categories that you can set on requests:

| Tag Key | Description | Example Values | |---------|-------------|----------------| | team | Your team or group | "backend", "ml-platform", "marketing" | | environment | Deployment environment | "development", "staging", "production" | | feature | Feature or use case | "search", "chat", "summarization" |

Tags are validated server-side. Your workspace admin can configure allowed values for each tag category via the dashboard. If a tag value is not in the allowed list, the request may be warned or rejected depending on your workspace's enforcement mode.

const result = await client.complete({
  messages: [{ role: 'user', content: 'Summarize this document...' }],
  tags: {
    team: 'backend',
    environment: 'production',
    feature: 'summarization',
  },
});

Note: The integration tag is reserved for system use (e.g., Cursor, Claude Code) and should not be set manually. The project tag is also available for workspace-level project attribution — see your dashboard for configuration.

Intelligent Model Routing

Model routing is fully managed by your workspace admin via the dashboard. The system uses HLE (Humanity's Last Exam) scores — a standardized benchmark — to determine model quality. Admins configure quality ceilings at three levels:

• Global ceiling: Set via the HLE slider in the dashboard. Applies to all requests.
• Tag-level ceilings: Set per tag (e.g., environment=development gets a lower ceiling to save costs).
• Integration-level ceilings: Set per integration (e.g., Cursor, Claude Code).

The routing engine picks the cheapest model whose HLE score meets the effective ceiling. HLE scores are maintained server-side and cannot be overridden by SDK callers.

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const result = await client.complete({
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  tags: { team: 'backend', environment: 'production' },
});

console.log(result.routing_info?.selected_model);           // e.g., "gpt-4o-mini"
console.log(result.routing_info?.selected_provider);        // e.g., "openai"
console.log(result.routing_info?.model_hle);                // e.g., 32.5
console.log(result.routing_info?.model_price_per_million);  // e.g., 0.15

Routing Response

Every complete() response includes routing_info with full transparency into the routing decision:

const info = result.routing_info;
console.log(`Model: ${info?.selected_model}`);
console.log(`Provider: ${info?.selected_provider}`);
console.log(`Model HLE: ${info?.model_hle}`);
console.log(`Effective HLE ceiling: ${info?.effective_hle}`);
console.log(`Ceiling source: ${info?.hle_source}`);  // "tag", "global", or "none"

Provider-Constrained Routing

Optionally constrain to a specific provider:

const result = await client.complete({
  messages: [{ role: 'user', content: 'Write a poem' }],
  llm_provider: 'anthropic',
});

With Compression Config

Control which message roles get compressed:

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const result = await client.complete({
  messages: [{ role: 'user', content: 'Hello!' }],
  compress: true,
  compress_output: false,
  compression_config: {
    compress_system: false,
    compress_user: true,
    compress_assistant: false,
    compress_only_last_n_user: 1,
  },
  temperature: 0.7,
  max_tokens: 1000,
  tags: { team: 'backend', environment: 'production' },
});

console.log(result.choices[0].message.content);
console.log(`Model used: ${result.routing_info?.selected_model}`);

API Reference

PcompresslrAPIClient

Main API client for intelligent model routing and compression.

Constructor

new PcompresslrAPIClient(apiKey?: string, apiUrl?: string, timeout?: number)

Parameters:

• apiKey (string, optional): LightReach API key. Falls back to LIGHTREACH_API_KEY or PCOMPRESLR_API_KEY env vars.
• apiUrl (string, optional): Override base API URL. Falls back to PCOMPRESLR_API_URL env var. Default: https://api.compress.lightreach.io
• timeout (number, optional): Request timeout in milliseconds. Default: 900000 (15 minutes)

Methods

complete(request: CompleteV2Request): Promise<CompleteResponse>

Messages-first completion with intelligent routing. Uses async job processing (enqueue + poll) for production reliability.

For direct synchronous calls, use completeSync() instead.

Request Parameters (CompleteV2Request):

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | messages | Message[] | required | Conversation history with role and content | | llm_provider | 'openai' \| 'anthropic' \| 'google' \| 'deepseek' \| 'moonshot' | — | Optional provider constraint. Omit for cross-provider optimization | | compress | boolean | true | Whether to compress messages | | compress_output | boolean | false | Advanced server hint. complete() still returns normal OpenAI-style text in choices[0].message.content | | compression_config | object | — | Per-role compression settings (see below) | | temperature | number | — | LLM temperature parameter | | max_tokens | number | — | Maximum tokens to generate | | tags | Record<string, string> | — | Tags for cost attribution and quality ceilings. Use team, environment, and/or feature keys | | max_history_messages | number | — | Limit conversation history length |

compression_config options:

{
  compress_system?: boolean;         // default: false
  compress_user?: boolean;           // default: true
  compress_assistant?: boolean;      // default: false
  compress_only_last_n_user?: number | null;  // default: 1
}

Response (CompleteResponse):

{
  id: string;                        // OpenAI-style completion id
  object: "chat.completion";
  created: number;                   // Unix timestamp
  model: string;
  choices: Array<{
    index: number;
    message: { role: "assistant"; content: string | null; tool_calls?: any[] };
    finish_reason: string | null;
  }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
  content: string;                   // Alias of choices[0].message.content
  compression_stats: {
    compression_enabled: boolean;
    original_tokens: number;
    compressed_tokens: number;
    token_savings: number;
    compression_ratio: number;
    token_count_exact?: boolean;
    token_count_source?: string;
    token_accounting_note?: string;
    processing_time_ms?: number;
  };
  llm_stats: {
    provider?: string;
    model?: string;
    input_tokens: number;
    output_tokens: number;
    total_tokens: number;
    finish_reason?: string | null;
  };
  routing_info?: {
    selected_model: string;          // Model chosen by system
    selected_provider: string;       // Provider chosen by system
    selected_model_id: string;
    model_hle: number;               // HLE score of selected model (server-computed)
    model_price_per_million: number;
    effective_hle: number | null;    // The quality ceiling that was applied
    hle_source: 'tag' | 'global' | 'none';
  };
  warnings?: string[];
  lightreach?: {                     // Namespaced LightReach metadata extension
    compression_stats?: object;
    llm_stats?: object;
    routing_info?: object;
    latency_ms?: number | null;
  };

  // Convenience aliases
  tokens_saved?: number;
  tokens_used?: number;
  compression_ratio?: number;
  cost_estimate?: number | null;
  savings_estimate?: number | null;
}

completeSync(request: CompleteV2Request): Promise<CompleteResponse>

Direct synchronous call to POST /api/v2/complete. Best for small/interactive usage. For production reliability, prefer complete() (async job + polling).

completeAsync(request, opts?): Promise<CompleteResponse>

Explicit async job flow with configurable polling. Called internally by complete().

Options:

• pollIntervalMs (number, default: 1000): Polling interval in milliseconds
• maxWaitMs (number, default: timeout): Maximum wait time
• idempotencyKey (string, optional): Idempotency key for job creation

healthCheck(): Promise<HealthCheckResponse>

Check API health status (GET /health).

Response:

{
  status: string;
  version?: string;
}

Message Types

type MessageRole = 'system' | 'developer' | 'user' | 'assistant';

interface Message {
  role: MessageRole;
  content: string;
}

Environment Variables

| Variable | Description | |----------|-------------| | PCOMPRESLR_API_KEY | Your LightReach API key (primary) | | LIGHTREACH_API_KEY | Your LightReach API key (alternative) | | PCOMPRESLR_API_URL | Override the API base URL (advanced/testing) |

Exceptions

| Exception | Description | |-----------|-------------| | PcompresslrAPIError | Base exception class | | APIKeyError | Invalid or missing API key | | RateLimitError | Rate limit exceeded | | APIRequestError | General API errors (including routing failures, tag validation errors) |

import { APIKeyError, RateLimitError, APIRequestError } from 'compress-lightreach';

try {
  const result = await client.complete({ messages: [...] });
} catch (error) {
  if (error instanceof APIKeyError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, please retry later');
  } else if (error instanceof APIRequestError) {
    console.error('API error:', error.message);
  }
}

How It Works

1. Compression: Identifies repeated substrings using efficient algorithms and replaces them with shorter placeholders, reducing token count
2. Routing: Selects the cheapest model that meets the admin-configured quality ceiling (global, tag-level, or integration-level)
3. LLM Call: Sends the compressed prompt to the selected model via your BYOK provider keys
4. Response Shaping: Returns standard OpenAI-style completion fields plus LightReach metadata extensions

Examples

Example 1: Complete with Compression

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const prompt = `
Write a story about a cat. The cat is very friendly. 
Write a story about a dog. The dog is very friendly.
Write a story about a bird. The bird is very friendly.
`;

const result = await client.complete({
  messages: [{ role: "user", content: prompt }],
  tags: { team: 'content', environment: 'production' },
});

console.log(result.choices[0].message.content);
console.log(`Model used: ${result.routing_info?.selected_model}`);
console.log(`Token savings: ${result.compression_stats.token_savings} tokens`);
console.log(`Compression ratio: ${(result.compression_stats.compression_ratio * 100).toFixed(2)}%`);

Example 2: Compression Config

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const result = await client.complete({
  messages: [{ role: "user", content: "Generate a long report with repeated sections..." }],
  compression_config: {
    compress_system: false,
    compress_user: true,
    compress_assistant: false,
    compress_only_last_n_user: 1,
  },
});

console.log(result.choices[0].message.content);

Example 3: Multi-turn Conversation

import { PcompresslrAPIClient } from 'compress-lightreach';

const client = new PcompresslrAPIClient("your-lightreach-api-key");

const result = await client.complete({
  messages: [
    { role: "system", content: "You are a helpful coding assistant." },
    { role: "user", content: "How do I read a file in Python?" },
    { role: "assistant", content: "You can use open() with a context manager..." },
    { role: "user", content: "How about writing to a file?" },
  ],
  compression_config: {
    compress_system: false,
    compress_user: true,
    compress_assistant: false,
    compress_only_last_n_user: 2,
  },
  tags: { team: 'engineering', feature: 'code-assistant' },
});

Getting an API Key

To use Compress Light Reach, you need an API key from compress.lightreach.io.

1. Visit compress.lightreach.io
2. Sign up for an account
3. Get your API key from the dashboard
4. Set it as an environment variable: export PCOMPRESLR_API_KEY=your-key

Security & Privacy

BYOK model: Provider keys (OpenAI/Anthropic/Google/etc.) are managed in the dashboard and never passed through this SDK. The SDK only uses your LightReach API key for authentication with the service.

Requirements

• Node.js 14.0.0 or higher
• TypeScript 5.3.0+ (for TypeScript projects)

License

MIT License - see LICENSE file for details.

Support

• Documentation: compress.lightreach.io/docs
• Issues: GitHub Issues
• Email: [email protected]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.