compress-lightreach 1.0.8 → 1.0.10

package/README.md

@@ -1,6 +1,6 @@
 # Compress Light Reach
 
-**AI cost management SDK with intelligent model routing, prompt compression, and real-time token tracking**
+**OpenAI-compatible LLM routing + compression SDK (superset responses with LightReach metadata)**
 
 [![npm version](https://badge.fury.io/js/compress-lightreach.svg)](https://badge.fury.io/js/compress-lightreach)
 [![Node.js 14+](https://img.shields.io/badge/node-14+-blue.svg)](https://nodejs.org/)
@@ -12,8 +12,7 @@ Compress Light Reach is a Node.js/TypeScript SDK that provides intelligent model
 
 - **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**: Perfect decompression guaranteed
-- **Output Compression**: Optional model output compression support
+- **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
@@ -52,7 +51,7 @@ const result = await client.complete({
   tags: { team: 'backend', environment: 'production' },
 });
 
-console.log(result.decompressed_response);
+console.log(result.choices[0].message.content);
 console.log(`Selected: ${result.routing_info?.selected_model}`);
 console.log(`Token savings: ${result.compression_stats.token_savings}`);
 ```
@@ -154,17 +153,6 @@ const result = await client.complete({
 });
 ```
 
-### With Output Compression
-
-```typescript
-const result = await client.complete({
-  messages: [{ role: 'user', content: 'Generate a long report...' }],
-  compress_output: true,
-});
-
-console.log(result.decompressed_response);
-```
-
 ### With Compression Config
 
 Control which message roles get compressed:
@@ -189,39 +177,10 @@ const result = await client.complete({
   tags: { team: 'backend', environment: 'production' },
 });
 
-console.log(result.decompressed_response);
+console.log(result.choices[0].message.content);
 console.log(`Model used: ${result.routing_info?.selected_model}`);
 ```
 
-### Compression Only (No LLM Call)
-
-```typescript
-import { PcompresslrAPIClient } from 'compress-lightreach';
-
-const client = new PcompresslrAPIClient("your-lightreach-api-key");
-
-const compressed = await client.compress(
-  "Your text with repeated content here...",
-  "gpt-4",
-  { team: 'backend' },
-);
-
-console.log(compressed.llm_format);
-console.log(`Compression ratio: ${compressed.compression_ratio}`);
-
-// Decompress later
-const decompressed = await client.decompress(compressed.llm_format);
-console.log(decompressed.decompressed);
-```
-
-### Command Line Interface
-
-```bash
-export PCOMPRESLR_API_KEY=your-api-key
-
-npx pcompresslr "Your prompt with repeated text here..."
-```
-
 ## API Reference
 
 ### `PcompresslrAPIClient`
@@ -254,7 +213,7 @@ For direct synchronous calls, use `completeSync()` instead.
 | `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` | Whether to request compressed output from LLM |
+| `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 |
@@ -276,8 +235,21 @@ For direct synchronous calls, use `completeSync()` instead.
 
 ```typescript
 {
-  content: string;                   // Final response content
-  decompressed_response: string;     // Final decompressed LLM response
+  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;
@@ -307,6 +279,12 @@ For direct synchronous calls, use `completeSync()` instead.
     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;
@@ -330,46 +308,6 @@ Explicit async job flow with configurable polling. Called internally by `complet
 - `maxWaitMs` (number, default: timeout): Maximum wait time
 - `idempotencyKey` (string, optional): Idempotency key for job creation
 
-##### `compress(prompt, model?, tags?): Promise<CompressResponse>`
-
-Compression-only (POST `/api/v1/compress`).
-
-**Parameters:**
-- `prompt` (string, required): Text to compress
-- `model` (string, optional): Model for tokenization. Default: `'gpt-4'`
-- `tags` (`Record<string, string>`, optional): Tags for attribution
-
-**Response (`CompressResponse`):**
-
-```typescript
-{
-  compressed: string;
-  dictionary: Record<string, string>;
-  llm_format: string;
-  compression_ratio: number;
-  original_size: number;
-  compressed_size: number;
-  processing_time_ms: number;
-  algorithm: string;
-}
-```
-
-##### `decompress(llmFormat): Promise<DecompressResponse>`
-
-Decompress an LLM-formatted compressed prompt (POST `/api/v1/decompress`).
-
-**Parameters:**
-- `llmFormat` (string, required): The `llm_format` string from a compress response
-
-**Response (`DecompressResponse`):**
-
-```typescript
-{
-  decompressed: string;
-  processing_time_ms: number;
-}
-```
-
 ##### `healthCheck(): Promise<HealthCheckResponse>`
 
 Check API health status (GET `/health`).
@@ -432,7 +370,7 @@ try {
 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. **Decompression**: Losslessly restores the model's response if output compression was enabled
+4. **Response Shaping**: Returns standard OpenAI-style completion fields plus LightReach metadata extensions
 
 ## Examples
 
@@ -454,13 +392,13 @@ const result = await client.complete({
   tags: { team: 'content', environment: 'production' },
 });
 
-console.log(result.decompressed_response);
+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: Output Compression
+### Example 2: Compression Config
 
 ```typescript
 import { PcompresslrAPIClient } from 'compress-lightreach';
@@ -469,10 +407,15 @@ const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 const result = await client.complete({
   messages: [{ role: "user", content: "Generate a long report with repeated sections..." }],
-  compress_output: true,
+  compression_config: {
+    compress_system: false,
+    compress_user: true,
+    compress_assistant: false,
+    compress_only_last_n_user: 1,
+  },
 });
 
-console.log(result.decompressed_response);
+console.log(result.choices[0].message.content);
 ```
 
 ### Example 3: Multi-turn Conversation

package/dist/api-client.d.ts

@@ -28,7 +28,27 @@ export interface DecompressResponse {
     processing_time_ms: number;
 }
 export interface CompleteResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: 'assistant';
+            content: string | null;
+            tool_calls?: Array<Record<string, any>>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
     content: string;
+    decompressed_response?: string;
+    text?: string;
     compression_stats: {
         compression_enabled: boolean;
         original_tokens: number;
@@ -75,6 +95,7 @@ export interface CompleteResponse {
     model_hle?: number | null;
     input_price_per_million?: number | null;
     output_price_per_million?: number | null;
+    lightreach?: Record<string, any>;
 }
 export type MessageRole = 'system' | 'developer' | 'user' | 'assistant';
 export interface Message {
@@ -152,6 +173,7 @@ export declare class PcompresslrAPIClient {
     private session;
     constructor(apiKey?: string, apiUrl?: string, timeout?: number);
     private makeRequest;
+    private toOpenAISupersetResponse;
     /**
      * Create async /complete job (POST /api/v1/complete/jobs).
      */

package/dist/api-client.js

@@ -141,6 +141,65 @@ class PcompresslrAPIClient {
             throw new APIRequestError(`Request failed: ${errorMessage}`);
         }
     }
+    toOpenAISupersetResponse(raw) {
+        const response = (raw && typeof raw === 'object') ? { ...raw } : {};
+        const llmStats = (response.llm_stats && typeof response.llm_stats === 'object') ? response.llm_stats : {};
+        const routingInfo = (response.routing_info && typeof response.routing_info === 'object') ? response.routing_info : {};
+        const content = (typeof response.content === 'string' && response.content) ||
+            (typeof response.decompressed_response === 'string' && response.decompressed_response) ||
+            (typeof response.text === 'string' && response.text) ||
+            '';
+        const model = response.model ||
+            response.model_used ||
+            routingInfo.selected_model ||
+            llmStats.model ||
+            'lightreach';
+        const promptTokens = Number(llmStats.input_tokens ?? 0) || 0;
+        const completionTokens = Number(llmStats.output_tokens ?? 0) || 0;
+        const totalTokens = Number(llmStats.total_tokens ?? (promptTokens + completionTokens)) || (promptTokens + completionTokens);
+        const finishReason = llmStats.finish_reason ?? 'stop';
+        const message = { role: 'assistant', content };
+        if (Array.isArray(response.tool_calls) && response.tool_calls.length > 0) {
+            message.tool_calls = response.tool_calls;
+            if (!content)
+                message.content = null;
+        }
+        response.id = String(response.id || `chatcmpl-${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`);
+        response.object = 'chat.completion';
+        response.created = Number(response.created || Math.floor(Date.now() / 1000));
+        response.model = String(model);
+        response.choices = Array.isArray(response.choices)
+            ? response.choices
+            : [{ index: 0, message, finish_reason: finishReason }];
+        response.usage = (response.usage && typeof response.usage === 'object')
+            ? response.usage
+            : {
+                prompt_tokens: promptTokens,
+                completion_tokens: completionTokens,
+                total_tokens: totalTokens,
+            };
+        response.content = content;
+        if (response.decompressed_response === undefined)
+            response.decompressed_response = content;
+        if (response.text === undefined)
+            response.text = content;
+        response.lightreach = {
+            content,
+            compression_stats: response.compression_stats,
+            llm_stats: response.llm_stats,
+            routing_info: response.routing_info,
+            warnings: response.warnings,
+            tokens_saved: response.tokens_saved,
+            tokens_used: response.tokens_used,
+            compression_ratio: response.compression_ratio,
+            cost_estimate: response.cost_estimate,
+            savings_estimate: response.savings_estimate,
+            provider_used: response.provider_used,
+            model_used: response.model_used,
+            latency_ms: llmStats.latency_ms ?? null,
+        };
+        return response;
+    }
     /**
      * Create async /complete job (POST /api/v1/complete/jobs).
      */
@@ -193,7 +252,7 @@ class PcompresslrAPIClient {
             const st = await this.getCompleteJob(jobId);
             if (st.status === 'succeeded') {
                 if (st.result)
-                    return st.result;
+                    return this.toOpenAISupersetResponse(st.result);
                 throw new APIRequestError('Async job succeeded but result was missing.');
             }
             if (st.status === 'failed' || st.status === 'canceled') {
@@ -285,7 +344,8 @@ class PcompresslrAPIClient {
             data.auto_select_by_hle = request.auto_select_by_hle;
         if (request.same_provider_only !== undefined)
             data.same_provider_only = request.same_provider_only;
-        return this.makeRequest('/api/v2/complete', data, 'POST');
+        const raw = await this.makeRequest('/api/v2/complete', data, 'POST');
+        return this.toOpenAISupersetResponse(raw);
     }
     /**
      * Messages-first complete with intelligent model selection.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Compress Light Reach - Intelligent compression algorithms for LLM prompts.
+ * Compress Light Reach - OpenAI-compatible routing + compression SDK.
  */
 export { __version__ } from './version';
 export { LightReach, Pcompresslr } from './core';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * Compress Light Reach - Intelligent compression algorithms for LLM prompts.
+ * Compress Light Reach - OpenAI-compatible routing + compression SDK.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PcompresslrAPIError = exports.APIRequestError = exports.RateLimitError = exports.APIKeyError = exports.PcompresslrAPIClient = exports.Pcompresslr = exports.LightReach = exports.__version__ = void 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "compress-lightreach",
-  "version": "1.0.8",
-  "description": "AI cost management SDK with intelligent model routing, prompt compression, and real-time token tracking",
+  "version": "1.0.10",
+  "description": "OpenAI-compatible LLM routing and compression SDK with LightReach metadata extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {