compress-lightreach 0.1.4 → 1.0.0

package/README.md

@@ -10,11 +10,16 @@ Compress Light Reach is a Node.js/TypeScript library that intelligently compress
 
 ## Features
 
+- **Token-aware compression**: Only replaces substrings >1 token with 1-token placeholders
+- **Dual algorithms**: 
+  - Fast greedy (~99% optimal) for daily use
+  - Optimal DP (O(n²)) for critical prompts
 - **Lossless**: Perfect decompression guaranteed
 - **Output compression**: Optional model output compression support
 - **Cloud API**: Uses Light Reach's cloud service for compression
 - **Model-aware**: Optimized for GPT-4, GPT-3.5-turbo, Claude, and more
 - **TypeScript**: Full TypeScript support with type definitions
+- **Intelligent Routing**: Automatic model selection based on quality requirements
 
 ## Installation
 
@@ -28,50 +33,109 @@ or
 yarn add compress-lightreach
 ```
 
-## Quick Start
+## Quick Start (v1.0.0)
 
-The `complete()` method is the only public interface for using Compress Light Reach. It handles compression, LLM call, and decompression in one request. Clients never see compressed prompts or dictionaries - everything is handled internally.
+The SDK uses **intelligent model routing** and targets `POST /api/v2/complete`.
+
+- Authenticate with your **LightReach API key** (env var `PCOMPRESLR_API_KEY`)
+- Manage **provider keys** (OpenAI/Anthropic/Google) in the dashboard (BYOK)
+- System automatically selects optimal model based on your requirements
 
 ```typescript
-import { Pcompresslr } from 'compress-lightreach';
-
-// Initialize compressor with LLM provider credentials
-const compressor = new Pcompresslr({
-  model: "gpt-4",
-  apiKey: "your-compress-api-key", // Or set PCOMPRESLR_API_KEY env var
-  llmProvider: "openai", // or "anthropic"
-  llmApiKey: "your-llm-api-key" // OpenAI or Anthropic API key
+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.' },
+  ],
+  desiredHle: 30,  // Quality preference (0-40, where 40 is SOTA)
 });
 
-// Complete a prompt (compresses, calls LLM, decompresses)
-const result = await compressor.complete("Your long prompt with repeated text here...");
+console.log(result.decompressed_response);
+console.log(`Selected: ${result.routing_info?.selected_model}`);
+console.log(`Token savings: ${result.compression_stats.token_savings}`);
+```
+
+### With Output Compression
+
+```typescript
+const result = await client.complete({
+  messages: [{ role: 'user', content: 'Generate a long report...' }],
+  desiredHle: 25,
+  compressOutput: true,
+});
 
-// Get the final decompressed response
 console.log(result.decompressed_response);
+```
 
-// View compression statistics
-console.log(`Token savings: ${result.compression_stats.token_savings} tokens`);
-console.log(`Compression ratio: ${(result.compression_stats.compression_ratio * 100).toFixed(2)}%`);
+### Intelligent Model Routing (v1.0.0)
+
+The system automatically selects the optimal model based on quality requirements and your available provider keys:
+
+```typescript
+import { PcompresslrAPIClient } from 'compress-lightreach';
+
+const client = new PcompresslrAPIClient("your-lightreach-api-key");
+
+// Cross-provider optimization: system picks cheapest model meeting your quality bar
+const result = await client.complete({
+  messages: [{role: 'user', content: 'Explain quantum computing'}],
+  desiredHle: 30,  // Quality preference (0-40, where 40 is SOTA)
+});
+
+// Check what was selected
+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
 ```
 
-### With Output Compression
+### Provider-Constrained Routing
+
+Optionally constrain to a specific provider:
 
 ```typescript
-import { Pcompresslr } from 'compress-lightreach';
-
-const compressor = new Pcompresslr({
-  model: "gpt-4",
-  apiKey: "your-api-key",
-  llmProvider: "openai",
-  llmApiKey: "your-llm-api-key",
-  compressOutput: true // Enable output compression
+// Only use OpenAI models, but pick the cheapest one meeting HLE 35
+const result = await client.complete({
+  messages: [{role: 'user', content: 'Write a poem'}],
+  llmProvider: 'openai',  // Optional: constrain to one provider
+  desiredHle: 35,
 });
+```
 
-// Complete with output compression enabled
-const result = await compressor.complete("Generate a long report with repeated sections...");
+### HLE Cascading with Admin Controls
 
-// Response is automatically decompressed
-console.log(result.decompressed_response);
+Admins can set quality **ceilings** via the dashboard (global or per-tag) to control costs. Your `desiredHle` is a preference, but requests will error if they exceed the admin-set ceiling:
+
+```typescript
+// Admin set global HLE ceiling to 30%
+// Requesting above the ceiling will error
+try {
+  const result = await client.complete({
+    messages: [{role: 'user', content: 'Process payment'}],
+    desiredHle: 35,  // ❌ ERROR: exceeds ceiling of 30
+    tags: {env: 'production'},
+  });
+} catch (e) {
+  console.error(e.message);  // "Requested HLE 35% exceeds workspace maximum of 30%"
+}
+
+// Correct usage: request within ceiling
+const result = await client.complete({
+  messages: [{role: 'user', content: 'Process payment'}],
+  desiredHle: 25,  // ✅ OK: below ceiling of 30
+  tags: {env: 'production'},
+});
+
+// Check if your HLE was lowered by admin ceiling
+if (result.routing_info?.hle_clamped) {
+  console.log(`HLE lowered from ${result.routing_info.requested_hle} ` +
+              `to ${result.routing_info.effective_hle} ` +
+              `by ${result.routing_info.hle_source}-level ceiling`);
+}
 ```
 
 ### Command Line Interface
@@ -81,50 +145,82 @@ console.log(result.decompressed_response);
 export PCOMPRESLR_API_KEY=your-api-key
 
 # Compress a prompt
-npx compress-lightreach "Your prompt with repeated text here..."
+# Run the CLI directly (the published binary name is `pcompresslr`)
+npx pcompresslr "Your prompt with repeated text here..."
 
 # Use optimal algorithm only
-npx compress-lightreach "Your prompt here" --optimal-only
+npx pcompresslr "Your prompt here" --optimal-only
 
 # Use greedy algorithm only
-npx compress-lightreach "Your prompt here" --greedy-only
+npx pcompresslr "Your prompt here" --greedy-only
 ```
 
 ## API Reference
 
-### `Pcompresslr`
+### `PcompresslrAPIClient`
 
-Main interface class for prompt compression.
+Main API client for intelligent model routing and compression.
 
-#### Constructor Options
+#### Constructor Parameters
 
-- `model` (string): LLM model name for tokenization (default: `"gpt-4"`)
-- `apiKey` (string, optional): API key for authentication. If not provided, checks `PCOMPRESLR_API_KEY` env var.
-- `compressOutput` (boolean): If true, instruct the model to output in compressed format (default: `false`)
-- `useOptimal` (boolean): If true, use optimal DP algorithm, else use fast greedy (default: `false`)
-- `llmProvider` (string, optional): LLM provider ('openai' or 'anthropic') for caching API key
-- `llmApiKey` (string, optional): LLM provider API key for use with `complete()` method
+- `apiKey` (string, optional): LightReach API key (or use `PCOMPRESLR_API_KEY` env var).
+- `apiUrl` (string, optional): Override base API URL (advanced/testing).
+- `timeout` (number): Request timeout in milliseconds (default: 120000).
 
 #### Methods
 
-- `complete(prompt, options?)`: Complete a prompt with compression, LLM call, and decompression in one request. Returns a Promise with `CompleteResponse` containing `decompressed_response`, `compression_stats`, `llm_stats`, and more. This is the only public method - clients never see compressed prompts or dictionaries.
-- `setLlmKey(provider, apiKey)`: Cache LLM provider API key for use with `complete()` method
-- `clearLlmKey()`: Clear cached LLM API key
-- `hasLlmKey()`: Check if LLM API key is cached
+##### `complete(request)`
 
-### `PcompresslrAPIClient`
+Messages-first completion with intelligent routing (POST `/api/v2/complete`).
 
-Low-level API client for direct interaction with the compression service. This is primarily for internal use. Most users should use `Pcompresslr.complete()` instead.
+**Parameters (CompleteV2Request):**
+- `messages` (required): Conversation history as array of objects with `role` and `content`
+- `llmProvider` (optional): Provider constraint (`'openai'`, `'anthropic'`, `'google'`, etc.). Omit for cross-provider optimization.
+- `desiredHle` (optional): Quality preference (0-40, where 40 is SOTA). Must not exceed admin's global/tag-level ceilings (request will error if it does).
+- `tags` (optional): Object of tags for cost attribution and tag-level HLE ceilings
+- `compress` (optional): Whether to compress messages (default: `true`)
+- `compressOutput` (optional): Whether to request compressed output from LLM (default: `false`)
+- `algorithm` (optional): Compression algorithm (`'greedy'` or `'optimal'`, default: `'greedy'`)
+- `temperature` (optional): LLM temperature parameter
+- `maxTokens` (optional): Maximum tokens to generate
+- `compressionConfig` (optional): Per-role compression settings
+- `maxHistoryMessages` (optional): Limit conversation history length
 
-#### Methods
+**Response (CompleteResponse) includes:**
+- `decompressed_response`: Final decompressed LLM response
+- `routing_info`: Details about model selection:
+  - `selected_model`: Model chosen by system
+  - `selected_provider`: Provider chosen by system
+  - `model_hle`: HLE score of selected model
+  - `effective_hle`: Effective HLE after applying admin ceilings (min of desired/tag/global)
+  - `hle_source`: `'request'`, `'tag'`, `'global'`, or `'none'`
+  - `hle_clamped`: `true` if admin ceiling lowered your `desiredHle`
+- `compression_stats`: Token savings statistics
+- `llm_stats`: Token usage from the LLM
+- `warnings`: Array of any warnings (including HLE ceiling notifications)
+
+##### `compress(prompt, model, algorithm, tags)`
+
+Compression-only (POST `/api/v1/compress`).
+
+##### `decompress(llmFormat)`
+
+Decompress an LLM-formatted compressed prompt (POST `/api/v1/decompress`).
 
-- `healthCheck()`: Check API health status
+##### `healthCheck()`
+
+Check API health status (GET `/health`).
+
+### Environment Variables
+
+- `PCOMPRESLR_API_KEY` (or `LIGHTREACH_API_KEY`): Your LightReach API key.
+- `PCOMPRESLR_API_URL`: Override the API base URL (advanced/testing).
 
 ### Exceptions
 
 - `APIKeyError`: Raised when API key is invalid or missing
 - `RateLimitError`: Raised when rate limit is exceeded
-- `APIRequestError`: Raised for general API errors
+- `APIRequestError`: Raised for general API errors (including routing failures)
 - `PcompresslrAPIError`: Base exception class
 
 ## How It Works
@@ -135,22 +231,18 @@ The library:
 1. Identifies repeated substrings using efficient suffix array algorithms
 2. Calculates token savings for each potential replacement
 3. Selects optimal replacements that reduce total token count
-4. Formats the result for easy LLM consumption
-5. Provides perfect decompression
+4. Intelligently routes to the best model based on your quality requirements
+5. Formats the result for easy LLM consumption
+6. Provides perfect decompression
 
 ## Examples
 
 ### Example 1: Using Complete Method (Recommended)
 
 ```typescript
-import { Pcompresslr } from 'compress-lightreach';
+import { PcompresslrAPIClient } from 'compress-lightreach';
 
-const compressor = new Pcompresslr({
-  model: "gpt-4",
-  apiKey: "your-compress-api-key",
-  llmProvider: "openai",
-  llmApiKey: "your-openai-key"
-});
+const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 const prompt = `
 Write a story about a cat. The cat is very friendly. 
@@ -159,9 +251,13 @@ Write a story about a bird. The bird is very friendly.
 `;
 
 // One call handles compression, LLM request, and decompression
-const result = await compressor.complete(prompt);
+const result = await client.complete({
+  messages: [{ role: "user", content: prompt }],
+  desiredHle: 30,
+});
 
 console.log(result.decompressed_response);
+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)}%`);
 ```
@@ -169,18 +265,16 @@ console.log(`Compression ratio: ${(result.compression_stats.compression_ratio *
 ### Example 2: Complete with Output Compression
 
 ```typescript
-import { Pcompresslr } from 'compress-lightreach';
+import { PcompresslrAPIClient } from 'compress-lightreach';
 
-const compressor = new Pcompresslr({
-  model: "gpt-4",
-  apiKey: "your-compress-api-key",
-  llmProvider: "openai",
-  llmApiKey: "your-openai-key",
-  compressOutput: true
-});
+const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 // Complete with output compression - response is automatically decompressed
-const result = await compressor.complete("Generate a long report with repeated sections...");
+const result = await client.complete({
+  messages: [{ role: "user", content: "Generate a long report with repeated sections..." }],
+  desiredHle: 35,
+  compressOutput: true
+});
 console.log(result.decompressed_response);
 ```
 
@@ -195,13 +289,7 @@ To use Compress Light Reach, you need an API key from [compress.lightreach.io](h
 
 ## Security & Privacy
 
-**We do not store LLM API keys anywhere.** When you provide an LLM API key (OpenAI, Anthropic, etc.) to use with the `complete()` method, it is:
-- Only used in-memory for the duration of the API request
-- Never stored on disk, in databases, or in logs
-- Never transmitted to any third-party services
-- Immediately discarded after the request completes
-
-Your LLM API keys remain secure and private. Only your Compress Light Reach API key is stored for authentication with our compression service.
+**BYOK model:** Provider keys (OpenAI/Anthropic/Google) 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
 
@@ -221,4 +309,3 @@ MIT License - see [LICENSE](../LICENSE) file for details.
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
-

package/dist/api-client.d.ts

@@ -45,6 +45,51 @@ export interface CompleteResponse {
         total_tokens: number;
     };
     warnings?: string[];
+    routing_info?: {
+        selected_model: string;
+        selected_provider: string;
+        selected_model_id: string;
+        model_hle: number;
+        model_price_per_million: number;
+        requested_hle: number | null;
+        effective_hle: number | null;
+        hle_source: 'request' | 'tag' | 'global' | 'none';
+        hle_clamped: boolean;
+    };
+    text?: string;
+    tokens_saved?: number;
+    tokens_used?: number;
+    compression_ratio?: number;
+    cost_estimate?: number | null;
+    savings_estimate?: number | null;
+}
+export type MessageRole = 'system' | 'developer' | 'user' | 'assistant';
+export interface Message {
+    role: MessageRole;
+    content: string;
+}
+export interface CompleteV2Request {
+    messages: Message[];
+    llm_provider?: 'openai' | 'anthropic' | 'google' | 'deepseek' | 'moonshot';
+    desired_hle?: number;
+    compress?: boolean;
+    compression_config?: {
+        compress_system?: boolean;
+        compress_user?: boolean;
+        compress_assistant?: boolean;
+        compress_only_last_n_user?: number | null;
+    };
+    compress_output?: boolean;
+    algorithm?: 'greedy' | 'optimal';
+    temperature?: number;
+    max_tokens?: number;
+    tags?: Record<string, string>;
+    max_history_messages?: number;
+    model?: string;
+    hle_target_percent?: number;
+    min_hle_score?: number;
+    auto_select_by_hle?: boolean;
+    same_provider_only?: boolean;
 }
 export interface HealthCheckResponse {
     status: string;
@@ -58,8 +103,36 @@ export declare class PcompresslrAPIClient {
     private session;
     constructor(apiKey?: string, apiUrl?: string, timeout?: number);
     private makeRequest;
-    compress(prompt: string, model?: string, algorithm?: "greedy" | "optimal"): Promise<CompressResponse>;
+    compress(prompt: string, model?: string, algorithm?: "greedy" | "optimal", tags?: Record<string, string>): Promise<CompressResponse>;
     decompress(llmFormat: string): Promise<DecompressResponse>;
     healthCheck(): Promise<HealthCheckResponse>;
-    complete(prompt: string, model: string, llmProvider: "openai" | "anthropic", llmApiKey: string, compress?: boolean, compressOutput?: boolean, algorithm?: "greedy" | "optimal", temperature?: number, maxTokens?: number): Promise<CompleteResponse>;
+    /**
+     * Messages-first complete with intelligent model selection (POST /api/v2/complete).
+     *
+     * v1.0.0: System automatically selects optimal model based on your provider keys,
+     * desired HLE, and admin's global/tag-level HLE ceilings.
+     *
+     * Provider API keys must be stored in your account (BYOK via dashboard).
+     *
+     * @example
+     * // Basic usage (cross-provider optimization)
+     * const response = await client.complete({
+     *   messages: [{role: 'user', content: 'Hello'}],
+     *   desired_hle: 30,
+     * });
+     *
+     * // Constrained to specific provider
+     * const response = await client.complete({
+     *   messages: [{role: 'user', content: 'Hello'}],
+     *   llm_provider: 'openai',
+     *   desired_hle: 35,
+     * });
+     *
+     * // Access routing info
+     * console.log(response.routing_info?.selected_model);
+     * if (response.routing_info?.hle_clamped) {
+     *   console.log('Admin ceiling lowered your desired HLE');
+     * }
+     */
+    complete(request: CompleteV2Request): Promise<CompleteResponse>;
 }

package/dist/api-client.js

@@ -8,6 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PcompresslrAPIClient = exports.APIRequestError = exports.RateLimitError = exports.APIKeyError = exports.PcompresslrAPIError = void 0;
 const axios_1 = __importDefault(require("axios"));
+const version_1 = require("./version");
 class PcompresslrAPIError extends Error {
     constructor(message) {
         super(message);
@@ -41,11 +42,11 @@ class APIRequestError extends PcompresslrAPIError {
 }
 exports.APIRequestError = APIRequestError;
 class PcompresslrAPIClient {
-    constructor(apiKey, apiUrl, timeout = 10000 // 10 seconds in milliseconds
+    constructor(apiKey, apiUrl, timeout = 120000 // 2 minutes - complete() calls LLM which can take 30+ seconds
     ) {
         this.DEFAULT_API_URL = "https://api.compress.lightreach.io";
         // Get API key from parameter or environment
-        this.apiKey = apiKey || process.env.PCOMPRESLR_API_KEY || '';
+        this.apiKey = apiKey || process.env.LIGHTREACH_API_KEY || process.env.PCOMPRESLR_API_KEY || '';
         if (!this.apiKey || !this.apiKey.trim()) {
             throw new APIKeyError("API key is required. Provide it as a parameter or set " +
                 "PCOMPRESLR_API_KEY environment variable.");
@@ -60,9 +61,11 @@ class PcompresslrAPIClient {
             baseURL: this.apiUrl,
             timeout: this.timeout,
             headers: {
+                // Prefer standard Bearer auth, but keep X-API-Key for backward compatibility.
+                'Authorization': `Bearer ${this.apiKey}`,
                 'X-API-Key': this.apiKey,
                 'Content-Type': 'application/json',
-                'User-Agent': 'compress-lightreach-nodejs/0.1.0'
+                'User-Agent': `compress-lightreach-nodejs/${version_1.__version__}`
             }
         });
         // Add response interceptor for retry logic
@@ -136,12 +139,15 @@ class PcompresslrAPIClient {
             throw new APIRequestError(`Request failed: ${errorMessage}`);
         }
     }
-    async compress(prompt, model = "gpt-4", algorithm = "greedy") {
+    async compress(prompt, model = "gpt-4", algorithm = "greedy", tags) {
         const data = {
             prompt,
             model,
             algorithm
         };
+        if (tags) {
+            data.tags = tags;
+        }
         return this.makeRequest("/api/v1/compress", data);
     }
     async decompress(llmFormat) {
@@ -166,23 +172,69 @@ class PcompresslrAPIClient {
             throw new APIRequestError(`Health check failed: ${errorMessage}`);
         }
     }
-    async complete(prompt, model, llmProvider, llmApiKey, compress = true, compressOutput = false, algorithm = "greedy", temperature, maxTokens) {
-        const data = {
-            prompt,
-            model,
-            llm_provider: llmProvider,
-            llm_api_key: llmApiKey,
-            compress,
-            compress_output: compressOutput,
-            algorithm,
-        };
-        if (temperature !== undefined) {
-            data.temperature = temperature;
+    /**
+     * Messages-first complete with intelligent model selection (POST /api/v2/complete).
+     *
+     * v1.0.0: System automatically selects optimal model based on your provider keys,
+     * desired HLE, and admin's global/tag-level HLE ceilings.
+     *
+     * Provider API keys must be stored in your account (BYOK via dashboard).
+     *
+     * @example
+     * // Basic usage (cross-provider optimization)
+     * const response = await client.complete({
+     *   messages: [{role: 'user', content: 'Hello'}],
+     *   desired_hle: 30,
+     * });
+     *
+     * // Constrained to specific provider
+     * const response = await client.complete({
+     *   messages: [{role: 'user', content: 'Hello'}],
+     *   llm_provider: 'openai',
+     *   desired_hle: 35,
+     * });
+     *
+     * // Access routing info
+     * console.log(response.routing_info?.selected_model);
+     * if (response.routing_info?.hle_clamped) {
+     *   console.log('Admin ceiling lowered your desired HLE');
+     * }
+     */
+    async complete(request) {
+        // Warn about deprecated parameters
+        if (request.model !== undefined) {
+            console.warn('[compress-lightreach v1.0.0] Parameter "model" is deprecated and will be ignored. ' +
+                'The system now selects models automatically.');
         }
-        if (maxTokens !== undefined) {
-            data.max_tokens = maxTokens;
+        if (request.hle_target_percent !== undefined ||
+            request.min_hle_score !== undefined ||
+            request.auto_select_by_hle !== undefined ||
+            request.same_provider_only !== undefined) {
+            console.warn('[compress-lightreach v1.0.0] HLE parameters have changed. ' +
+                'Use "desired_hle" and optional "llm_provider" instead.');
         }
-        return this.makeRequest("/api/v1/complete", data);
+        const data = {
+            messages: request.messages,
+            compress: request.compress ?? true,
+            compress_output: request.compress_output ?? false,
+            algorithm: request.algorithm ?? 'greedy',
+        };
+        // v1.0.0 parameters
+        if (request.llm_provider !== undefined)
+            data.llm_provider = request.llm_provider;
+        if (request.desired_hle !== undefined)
+            data.desired_hle = request.desired_hle;
+        if (request.compression_config)
+            data.compression_config = request.compression_config;
+        if (request.temperature !== undefined)
+            data.temperature = request.temperature;
+        if (request.max_tokens !== undefined)
+            data.max_tokens = request.max_tokens;
+        if (request.tags !== undefined)
+            data.tags = request.tags;
+        if (request.max_history_messages !== undefined)
+            data.max_history_messages = request.max_history_messages;
+        return this.makeRequest("/api/v2/complete", data);
     }
 }
 exports.PcompresslrAPIClient = PcompresslrAPIClient;

package/dist/cli.js

@@ -13,7 +13,7 @@ async function main() {
         console.log('  pcompresslr "hello world hello world hello world"');
         console.log('  pcompresslr "your prompt here" --greedy-only  # Only greedy');
         console.log('  pcompresslr "your prompt here" --optimal-only  # Only optimal');
-        console.log("\nNote: Requires PCOMPRESLR_API_KEY environment variable or API key parameter");
+        console.log("\nNote: Requires PCOMPRESLR_API_KEY environment variable");
         process.exit(0);
     }
     let prompt = args.join(" ");

package/dist/core.d.ts

@@ -1,47 +1,58 @@
 /**
- * Core Pcompresslr class for compressing prompts and optionally model outputs.
+ * SDK client for interacting with the LightReach/Compress API.
+ *
+ * v0.2.0 is a breaking release:
+ * - complete() is messages-first and targets POST /api/v2/complete
+ * - provider API keys are not accepted by this SDK (BYOK via dashboard)
  */
-import { CompleteResponse } from './api-client';
+import { CompleteResponse, Message, CompressResponse } from './api-client';
 /**
- * Main interface for prompt compression with optional output compression.
- *
- * Usage:
- *   // Complete a prompt (compresses, calls LLM, decompresses)
- *   const compressor = new Pcompresslr({
- *     model: "gpt-4",
- *     apiKey: "your-key",
- *     llmProvider: "openai",
- *     llmApiKey: "your-llm-key"
- *   });
- *   const result = await compressor.complete("Your prompt here");
- *   console.log(result.decompressed_response);
+ * User-facing compression config (camelCase).
  */
-export declare class Pcompresslr {
-    private model;
-    private compressOutput;
-    private useOptimal;
-    private llmProvider?;
-    private llmApiKey?;
+export interface CompressionConfig {
+    compressSystem?: boolean;
+    compressUser?: boolean;
+    compressAssistant?: boolean;
+    compressOnlyLastNUser?: number | null;
+}
+export interface CompleteOptions {
+    messages: Message[];
+    model?: string;
+    provider?: 'openai' | 'anthropic' | 'google';
+    compress?: boolean;
+    compressionConfig?: CompressionConfig;
+    compressOutput?: boolean;
+    useOptimal?: boolean;
+    hleTargetPercent?: number;
+    minHleScore?: number;
+    autoSelectByHle?: boolean;
+    sameProviderOnly?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+    tags?: Record<string, string>;
+    maxHistoryMessages?: number;
+}
+export declare class LightReach {
     private apiClient;
+    private defaultModel;
+    private defaultProvider;
+    private useOptimal;
     constructor(options?: {
-        model?: string;
         apiKey?: string;
-        compressOutput?: boolean;
+        apiUrl?: string;
+        defaultModel?: string;
+        defaultProvider?: 'openai' | 'anthropic' | 'google';
         useOptimal?: boolean;
-        llmProvider?: "openai" | "anthropic";
-        llmApiKey?: string;
     });
-    setLlmKey(provider: "openai" | "anthropic", apiKey: string): void;
-    clearLlmKey(): void;
-    hasLlmKey(): boolean;
-    complete(prompt: string, options?: {
+    complete(options: CompleteOptions): Promise<CompleteResponse>;
+    /**
+     * Compress text without making an LLM call (POST /api/v1/compress).
+     */
+    compress(text: string, options?: {
         model?: string;
-        llmProvider?: "openai" | "anthropic";
-        llmApiKey?: string;
-        compress?: boolean;
-        compressOutput?: boolean;
-        useOptimal?: boolean;
-        temperature?: number;
-        maxTokens?: number;
-    }): Promise<CompleteResponse>;
+        algorithm?: 'greedy' | 'optimal';
+        tags?: Record<string, string>;
+    }): Promise<CompressResponse>;
+}
+export declare class Pcompresslr extends LightReach {
 }

package/dist/core.js

@@ -1,152 +1,89 @@
 "use strict";
 /**
- * Core Pcompresslr class for compressing prompts and optionally model outputs.
+ * SDK client for interacting with the LightReach/Compress API.
+ *
+ * v0.2.0 is a breaking release:
+ * - complete() is messages-first and targets POST /api/v2/complete
+ * - provider API keys are not accepted by this SDK (BYOK via dashboard)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Pcompresslr = void 0;
+exports.Pcompresslr = exports.LightReach = void 0;
 const api_client_1 = require("./api-client");
-/**
- * Main interface for prompt compression with optional output compression.
- *
- * Usage:
- *   // Complete a prompt (compresses, calls LLM, decompresses)
- *   const compressor = new Pcompresslr({
- *     model: "gpt-4",
- *     apiKey: "your-key",
- *     llmProvider: "openai",
- *     llmApiKey: "your-llm-key"
- *   });
- *   const result = await compressor.complete("Your prompt here");
- *   console.log(result.decompressed_response);
- */
-class Pcompresslr {
+class LightReach {
     constructor(options = {}) {
-        /**
-         * Initialize the compressor.
-         *
-         * @param options.model - LLM model name for tokenization (e.g., 'gpt-4', 'gpt-3.5-turbo')
-         * @param options.apiKey - API key for authentication. If not provided, checks PCOMPRESLR_API_KEY env var.
-         * @param options.compressOutput - If true, instruct the model to output in compressed format
-         * @param options.useOptimal - If true, use optimal DP algorithm, else use fast greedy
-         * @param options.llmProvider - LLM provider ('openai' or 'anthropic') - for caching LLM API key
-         * @param options.llmApiKey - LLM provider API key - cached for use with complete() method
-         *
-         * Note:
-         *   When compressOutput=true, the input prompt size will increase due to
-         *   compression instructions. The benefit is that the model's output will
-         *   also be compressed, potentially saving tokens on the response.
-         *
-         * @throws APIKeyError - If API key is not provided and not found in environment
-         */
-        this.model = options.model || "gpt-4";
-        this.compressOutput = options.compressOutput || false;
-        this.useOptimal = options.useOptimal || false;
-        this.llmProvider = options.llmProvider;
-        this.llmApiKey = options.llmApiKey;
-        // Initialize API client (uses production URL by default, can be overridden via PCOMPRESLR_API_URL env var)
-        this.apiClient = new api_client_1.PcompresslrAPIClient(options.apiKey);
-    }
-    setLlmKey(provider, apiKey) {
-        /**
-         * Set LLM provider API key for use with complete() method.
-         *
-         * @param provider - LLM provider ('openai' or 'anthropic')
-         * @param apiKey - LLM provider API key
-         */
-        if (provider !== "openai" && provider !== "anthropic") {
-            throw new Error(`Unsupported provider: ${provider}. Must be 'openai' or 'anthropic'`);
-        }
-        this.llmProvider = provider;
-        this.llmApiKey = apiKey;
-    }
-    clearLlmKey() {
-        /**Clear cached LLM provider API key.*/
-        this.llmProvider = undefined;
-        this.llmApiKey = undefined;
-    }
-    hasLlmKey() {
-        /**Check if LLM API key is set.*/
-        return this.llmProvider !== undefined && this.llmApiKey !== undefined;
+        this.defaultModel = options.defaultModel ?? 'gpt-4';
+        this.defaultProvider = options.defaultProvider ?? 'openai';
+        this.useOptimal = options.useOptimal ?? false;
+        this.apiClient = new api_client_1.PcompresslrAPIClient(options.apiKey, options.apiUrl);
     }
-    async complete(prompt, options) {
-        /**
-         * Complete a prompt with compression, LLM call, and decompression in one request.
-         *
-         * This is the only public method for using the compression service. Clients never
-         * see compressed prompts or dictionaries - everything is handled internally.
-         *
-         * @param prompt - The prompt to complete
-         * @param options.model - LLM model name. If undefined, uses the model from constructor.
-         * @param options.llmProvider - LLM provider ('openai' or 'anthropic'). If undefined, uses cached provider or requires it.
-         * @param options.llmApiKey - LLM provider API key. If undefined, uses cached key or requires it.
-         * @param options.compress - Whether to compress the prompt (default: true)
-         * @param options.compressOutput - Whether to request compressed output from LLM (default: false)
-         * @param options.useOptimal - Whether to use optimal algorithm. If undefined, uses constructor setting.
-         * @param options.temperature - LLM temperature setting (optional)
-         * @param options.maxTokens - Maximum tokens to generate (optional)
-         *
-         * @returns Dictionary containing:
-         *   - decompressed_response: Final decompressed response
-         *   - compression_stats: Input compression statistics
-         *   - llm_stats: LLM usage statistics
-         *   - warnings: Any warnings
-         *
-         * @throws Error - If LLM provider/key not provided and not cached
-         * @throws APIKeyError - If API key is invalid
-         * @throws RateLimitError - If rate limit is exceeded
-         * @throws APIRequestError - For other API errors
-         */
-        // Prompt is required for complete()
-        if (!prompt) {
-            throw new Error("prompt is required for complete(). Provide it as a parameter.");
-        }
-        // Use model from parameter or constructor
-        const modelToUse = options?.model || this.model;
-        // Get LLM provider - from parameter, cached, or error
-        const providerToUse = options?.llmProvider || this.llmProvider;
-        if (!providerToUse) {
-            throw new Error("LLM provider is required. Provide it as a parameter or set it in constructor/setLlmKey().");
-        }
-        // Get LLM API key - from parameter, cached, or error
-        const keyToUse = options?.llmApiKey || this.llmApiKey;
-        if (!keyToUse) {
-            throw new Error("LLM API key is required. Provide it as a parameter or set it in constructor/setLlmKey().");
-        }
-        // Cache the provider and key if provided
-        if (options?.llmProvider && options?.llmApiKey) {
-            this.llmProvider = options.llmProvider;
-            this.llmApiKey = options.llmApiKey;
-        }
-        // Determine algorithm
-        const useOptimalToUse = options?.useOptimal !== undefined
-            ? options.useOptimal
-            : this.useOptimal;
-        const algorithm = useOptimalToUse ? "optimal" : "greedy";
-        // Make the complete request
+    async complete(options) {
+        const algorithm = (options.useOptimal ?? this.useOptimal) ? 'optimal' : 'greedy';
+        const cfg = options.compressionConfig
+            ? {
+                compress_system: options.compressionConfig.compressSystem ?? false,
+                compress_user: options.compressionConfig.compressUser ?? true,
+                compress_assistant: options.compressionConfig.compressAssistant ?? false,
+                compress_only_last_n_user: options.compressionConfig.compressOnlyLastNUser ?? 1,
+            }
+            : undefined;
         try {
-            const result = await this.apiClient.complete(prompt, modelToUse, providerToUse, keyToUse, options?.compress !== false, // default true
-            options?.compressOutput || false, // default false
-            algorithm, options?.temperature, options?.maxTokens);
-            return result;
+            const resp = await this.apiClient.complete({
+                messages: options.messages,
+                model: options.model ?? this.defaultModel,
+                llm_provider: options.provider ?? this.defaultProvider,
+                compress: options.compress ?? true,
+                compression_config: cfg,
+                compress_output: options.compressOutput ?? false,
+                algorithm,
+                hle_target_percent: options.hleTargetPercent,
+                min_hle_score: options.minHleScore,
+                auto_select_by_hle: options.autoSelectByHle,
+                same_provider_only: options.sameProviderOnly,
+                temperature: options.temperature,
+                max_tokens: options.maxTokens,
+                tags: options.tags,
+                max_history_messages: options.maxHistoryMessages,
+            });
+            // Add helpful aliases to better match the Feature 0.6 spec without changing backend response.
+            // We do NOT fabricate cost estimates here since the API response does not include pricing data.
+            return {
+                ...resp,
+                text: resp.text ?? resp.decompressed_response,
+                tokens_saved: resp.tokens_saved ?? resp.compression_stats?.token_savings,
+                tokens_used: resp.tokens_used ?? resp.llm_stats?.total_tokens,
+                compression_ratio: resp.compression_ratio ?? resp.compression_stats?.compression_ratio,
+                cost_estimate: resp.cost_estimate ?? null,
+                savings_estimate: resp.savings_estimate ?? null,
+            };
         }
         catch (error) {
             if (error instanceof api_client_1.APIKeyError) {
                 throw new api_client_1.APIKeyError(`${error.message}\n\n` +
-                    "To get an API key, visit https://compress.lightreach.io or " +
-                    "set the PCOMPRESLR_API_KEY environment variable.");
+                    'To get an API key, visit https://compress.lightreach.io or ' +
+                    'set the PCOMPRESLR_API_KEY environment variable.');
             }
             else if (error instanceof api_client_1.RateLimitError) {
                 throw new api_client_1.RateLimitError(`${error.message}\n\n` +
                     "You've exceeded your rate limit. Please wait before making more requests, " +
-                    "or upgrade your subscription plan.");
+                    'or upgrade your subscription plan.');
             }
             else if (error instanceof api_client_1.APIRequestError) {
                 throw new api_client_1.APIRequestError(`${error.message}\n\n` +
-                    "If this problem persists, please check https://compress.lightreach.io/status " +
-                    "or contact support.");
+                    'If this problem persists, please check https://compress.lightreach.io/status ' +
+                    'or contact support.');
             }
             throw error;
         }
     }
+    /**
+     * Compress text without making an LLM call (POST /api/v1/compress).
+     */
+    async compress(text, options) {
+        return await this.apiClient.compress(text, options?.model ?? this.defaultModel, options?.algorithm ?? 'greedy', options?.tags);
+    }
+}
+exports.LightReach = LightReach;
+// Backwards import name (API is still a breaking change vs v0.1.x)
+class Pcompresslr extends LightReach {
 }
 exports.Pcompresslr = Pcompresslr;

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * Compress Light Reach - Intelligent compression algorithms for LLM prompts.
  */
 export { __version__ } from './version';
-export { Pcompresslr } from './core';
+export { LightReach, Pcompresslr } from './core';
+export type { CompressionConfig, CompleteOptions } from './core';
 export { PcompresslrAPIClient, APIKeyError, RateLimitError, APIRequestError, PcompresslrAPIError, } from './api-client';
-export type { CompressResponse, DecompressResponse, CompleteResponse, HealthCheckResponse, } from './api-client';
+export type { CompressResponse, DecompressResponse, CompleteResponse, HealthCheckResponse, Message, MessageRole, CompleteV2Request, } from './api-client';

package/dist/index.js

@@ -3,11 +3,12 @@
  * Compress Light Reach - Intelligent compression algorithms for LLM prompts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PcompresslrAPIError = exports.APIRequestError = exports.RateLimitError = exports.APIKeyError = exports.PcompresslrAPIClient = exports.Pcompresslr = exports.__version__ = void 0;
+exports.PcompresslrAPIError = exports.APIRequestError = exports.RateLimitError = exports.APIKeyError = exports.PcompresslrAPIClient = exports.Pcompresslr = exports.LightReach = exports.__version__ = void 0;
 var version_1 = require("./version");
 Object.defineProperty(exports, "__version__", { enumerable: true, get: function () { return version_1.__version__; } });
-// Export main interface class
+// Export main interface classes/types
 var core_1 = require("./core");
+Object.defineProperty(exports, "LightReach", { enumerable: true, get: function () { return core_1.LightReach; } });
 Object.defineProperty(exports, "Pcompresslr", { enumerable: true, get: function () { return core_1.Pcompresslr; } });
 // Export API client and exceptions
 var api_client_1 = require("./api-client");

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * Version information for compress-lightreach package.
  */
-export declare const __version__ = "0.1.2";
+export declare const __version__ = "1.0.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__version__ = void 0;
-exports.__version__ = "0.1.2";
+exports.__version__ = "1.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compress-lightreach",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "description": "Intelligent compression algorithms for LLM prompts that reduce token usage",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,8 +8,7 @@
     "pcompresslr": "./dist/cli.js"
   },
   "scripts": {
-    "increment-version": "node increment-version.js",
-    "build": "npm run increment-version && tsc",
+    "build": "tsc",
     "prepublishOnly": "npm run build",
     "test": "jest",
     "test:watch": "jest --watch",