compress-lightreach 1.0.2 → 1.0.5

package/README.md

@@ -109,20 +109,16 @@ const result = await client.complete({
 
 ### HLE Cascading with Admin Controls
 
-Admins can set quality **ceilings** via the dashboard (global or per-tag) to control costs. Your `desired_hle` is a preference, but requests will error if they exceed the admin-set ceiling:
+Admins can set quality **ceilings** via the dashboard (global or per-tag) to control costs. Your `desired_hle` is a preference; if it exceeds an admin-set ceiling, the request will **silently clamp** to the ceiling and proceed.
 
 ```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' }],
-    desired_hle: 35,  // ERROR: exceeds ceiling of 30
-    tags: { env: 'production' },
-  });
-} catch (e) {
-  console.error(e.message);  // "Requested HLE 35% exceeds workspace maximum of 30%"
-}
+// Requesting above the ceiling will be clamped to 30 (no error)
+const result = await client.complete({
+  messages: [{ role: 'user', content: 'Process payment' }],
+  desired_hle: 35,  // Will be clamped down to 30
+  tags: { env: 'production' },
+});
 
 // Correct usage: request within ceiling
 const result = await client.complete({
@@ -131,7 +127,7 @@ const result = await client.complete({
   tags: { env: 'production' },
 });
 
-// Check if your HLE was lowered by admin ceiling
+// Check if your HLE was lowered by an admin ceiling
 if (result.routing_info?.hle_clamped) {
   console.log(`HLE lowered from ${result.routing_info.requested_hle} ` +
               `to ${result.routing_info.effective_hle} ` +
@@ -139,38 +135,36 @@ if (result.routing_info?.hle_clamped) {
 }
 ```
 
-### Using the LightReach Wrapper Class
+### With Compression Config
 
-For a more ergonomic API with camelCase parameters, use the `LightReach` class:
+Configure per-role compression settings:
 
 ```typescript
-import { LightReach } from 'compress-lightreach';
+import { PcompresslrAPIClient } from 'compress-lightreach';
 
-const client = new LightReach({
-  apiKey: 'your-lightreach-api-key',
-  defaultModel: 'gpt-4',
-  defaultProvider: 'openai',
-  useOptimal: false,  // Use greedy algorithm by default
-});
+const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 const result = await client.complete({
   messages: [{ role: 'user', content: 'Hello!' }],
+  desired_hle: 30,
   compress: true,
-  compressOutput: false,
-  compressionConfig: {
-    compressSystem: false,
-    compressUser: true,
-    compressAssistant: false,
-    compressOnlyLastNUser: 1,
+  compress_output: false,
+  compression_config: {
+    compress_system: false,
+    compress_user: true,
+    compress_assistant: false,
+    compress_only_last_n_user: 1,
   },
   temperature: 0.7,
-  maxTokens: 1000,
+  max_tokens: 1000,
   tags: { env: 'production' },
 });
 
 console.log(result.decompressed_response);
+console.log(`Model used: ${result.routing_info?.selected_model}`);
 ```
 
+
 ### Compression Only (No LLM Call)
 
 ```typescript
@@ -239,7 +233,7 @@ Messages-first completion with intelligent routing (POST `/api/v2/complete`).
 |-----------|------|---------|-------------|
 | `messages` | `Message[]` | required | Conversation history with `role` and `content` |
 | `llm_provider` | `'openai' \| 'anthropic' \| 'google' \| 'deepseek' \| 'moonshot'` | — | Optional provider constraint. Omit for cross-provider optimization |
-| `desired_hle` | `number` | — | Quality preference (0-40, where 40 is SOTA). Must not exceed admin ceilings |
+| `desired_hle` | `number` | — | Quality preference (0-40, where 40 is SOTA). If above an admin ceiling, it is clamped down |
 | `compress` | `boolean` | `true` | Whether to compress messages |
 | `compress_output` | `boolean` | `false` | Whether to request compressed output from LLM |
 | `algorithm` | `'greedy' \| 'optimal'` | `'greedy'` | Compression algorithm |
@@ -355,56 +349,6 @@ Check API health status (GET `/health`).
 }
 ```
 
-### `LightReach` Class
-
-Convenience wrapper with camelCase parameters.
-
-#### Constructor
-
-```typescript
-new LightReach(options?: {
-  apiKey?: string;
-  apiUrl?: string;
-  defaultModel?: string;      // Default: 'gpt-4'
-  defaultProvider?: 'openai' | 'anthropic' | 'google';  // Default: 'openai'
-  useOptimal?: boolean;       // Default: false (use greedy)
-})
-```
-
-#### Methods
-
-##### `complete(options: CompleteOptions): Promise<CompleteResponse>`
-
-```typescript
-interface CompleteOptions {
-  messages: Message[];
-  model?: string;
-  provider?: 'openai' | 'anthropic' | 'google';
-  compress?: boolean;
-  compressionConfig?: {
-    compressSystem?: boolean;
-    compressUser?: boolean;
-    compressAssistant?: boolean;
-    compressOnlyLastNUser?: number | null;
-  };
-  compressOutput?: boolean;
-  useOptimal?: boolean;
-  temperature?: number;
-  maxTokens?: number;
-  tags?: Record<string, string>;
-  maxHistoryMessages?: number;
-}
-```
-
-##### `compress(text, options?): Promise<CompressResponse>`
-
-```typescript
-await client.compress(text, {
-  model?: string;
-  algorithm?: 'greedy' | 'optimal';
-  tags?: Record<string, string>;
-});
-```
 
 ### Message Types
 

package/dist/api-client.d.ts

@@ -95,6 +95,23 @@ export interface HealthCheckResponse {
     status: string;
     version?: string;
 }
+export type CompleteJobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled';
+export interface CompleteJobCreateResponse {
+    job_id: string;
+    status: CompleteJobStatus;
+    status_url: string;
+}
+export interface CompleteJobStatusResponse {
+    job_id: string;
+    status: CompleteJobStatus;
+    phase?: string | null;
+    progress?: number | null;
+    created_at?: string | null;
+    started_at?: string | null;
+    finished_at?: string | null;
+    result?: any;
+    error?: any;
+}
 export declare class PcompresslrAPIClient {
     private readonly DEFAULT_API_URL;
     private apiKey;
@@ -103,9 +120,34 @@ export declare class PcompresslrAPIClient {
     private session;
     constructor(apiKey?: string, apiUrl?: string, timeout?: number);
     private makeRequest;
+    /**
+     * Create async /complete job (POST /api/v1/complete/jobs).
+     */
+    createCompleteJob(request: CompleteV2Request, opts?: {
+        idempotencyKey?: string;
+    }): Promise<CompleteJobCreateResponse>;
+    /**
+     * Poll async /complete job (GET /api/v1/complete/jobs/{job_id}).
+     */
+    getCompleteJob(jobId: string): Promise<CompleteJobStatusResponse>;
+    /**
+     * Production-safe complete: enqueue + poll async job endpoints.
+     */
+    completeAsync(request: CompleteV2Request, opts?: {
+        pollIntervalMs?: number;
+        maxWaitMs?: number;
+        idempotencyKey?: string;
+    }): Promise<CompleteResponse>;
     compress(prompt: string, model?: string, algorithm?: "greedy" | "optimal", tags?: Record<string, string>): Promise<CompressResponse>;
     decompress(llmFormat: string): Promise<DecompressResponse>;
     healthCheck(): Promise<HealthCheckResponse>;
+    /**
+     * Direct (non-job) complete call (POST /api/v2/complete).
+     *
+     * This hits the synchronous endpoint and is best-effort for small/interactive usage.
+     * For production reliability, prefer `complete()` (async job + polling).
+     */
+    completeSync(request: CompleteV2Request): Promise<CompleteResponse>;
     /**
      * Messages-first complete with intelligent model selection (POST /api/v2/complete).
      *

package/dist/api-client.js

@@ -42,7 +42,7 @@ class APIRequestError extends PcompresslrAPIError {
 }
 exports.APIRequestError = APIRequestError;
 class PcompresslrAPIClient {
-    constructor(apiKey, apiUrl, timeout = 120000 // 2 minutes - complete() calls LLM which can take 30+ seconds
+    constructor(apiKey, apiUrl, timeout = 900000 // 15 minutes - complete() can include long upstream LLM calls
     ) {
         this.DEFAULT_API_URL = "https://api.compress.lightreach.io";
         // Get API key from parameter or environment
@@ -89,7 +89,7 @@ class PcompresslrAPIClient {
             return Promise.reject(error);
         });
     }
-    async makeRequest(endpoint, data, method = 'POST') {
+    async makeRequest(endpoint, data, method = 'POST', opts) {
         const url = `${this.apiUrl}${endpoint}`;
         try {
             const response = await this.session.request({
@@ -97,6 +97,8 @@ class PcompresslrAPIClient {
                 url: endpoint,
                 data: method === 'POST' ? data : undefined,
                 params: method === 'GET' ? data : undefined,
+                headers: opts?.headers,
+                timeout: opts?.timeoutMs,
             });
             return response.data;
         }
@@ -139,6 +141,71 @@ class PcompresslrAPIClient {
             throw new APIRequestError(`Request failed: ${errorMessage}`);
         }
     }
+    /**
+     * Create async /complete job (POST /api/v1/complete/jobs).
+     */
+    async createCompleteJob(request, opts) {
+        const data = {
+            messages: request.messages,
+            compress: request.compress ?? true,
+            compress_output: request.compress_output ?? false,
+            algorithm: request.algorithm ?? 'greedy',
+        };
+        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;
+        const headers = {};
+        if (opts?.idempotencyKey)
+            headers['Idempotency-Key'] = opts.idempotencyKey;
+        return this.makeRequest('/api/v1/complete/jobs', data, 'POST', { headers });
+    }
+    /**
+     * Poll async /complete job (GET /api/v1/complete/jobs/{job_id}).
+     */
+    async getCompleteJob(jobId) {
+        if (!jobId)
+            throw new APIRequestError('jobId is required');
+        // Keep polls short even if overall client timeout is high.
+        return this.makeRequest(`/api/v1/complete/jobs/${jobId}`, {}, 'GET', { timeoutMs: Math.min(this.timeout, 30000) });
+    }
+    /**
+     * Production-safe complete: enqueue + poll async job endpoints.
+     */
+    async completeAsync(request, opts) {
+        const job = await this.createCompleteJob(request, { idempotencyKey: opts?.idempotencyKey });
+        const jobId = job.job_id;
+        const pollIntervalMs = Math.max(200, opts?.pollIntervalMs ?? 1000);
+        const maxWaitMs = opts?.maxWaitMs ?? this.timeout;
+        const deadline = Date.now() + maxWaitMs;
+        let interval = pollIntervalMs;
+        while (true) {
+            const st = await this.getCompleteJob(jobId);
+            if (st.status === 'succeeded') {
+                if (st.result)
+                    return st.result;
+                throw new APIRequestError('Async job succeeded but result was missing.');
+            }
+            if (st.status === 'failed' || st.status === 'canceled') {
+                throw new APIRequestError(`Async complete job ${st.status}: ${JSON.stringify(st.error ?? {})}`);
+            }
+            if (Date.now() > deadline) {
+                throw new APIRequestError(`Async complete job timed out after ${maxWaitMs}ms (status=${st.status}).`);
+            }
+            await new Promise((r) => setTimeout(r, interval));
+            interval = Math.min(Math.floor(interval * 1.2), 2000);
+        }
+    }
     async compress(prompt, model = "gpt-4", algorithm = "greedy", tags) {
         const data = {
             prompt,
@@ -172,6 +239,47 @@ class PcompresslrAPIClient {
             throw new APIRequestError(`Health check failed: ${errorMessage}`);
         }
     }
+    /**
+     * Direct (non-job) complete call (POST /api/v2/complete).
+     *
+     * This hits the synchronous endpoint and is best-effort for small/interactive usage.
+     * For production reliability, prefer `complete()` (async job + polling).
+     */
+    async completeSync(request) {
+        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;
+        // Deprecated / backward compatible parameters (still accepted by some deployments)
+        if (request.model !== undefined)
+            data.model = request.model;
+        if (request.hle_target_percent !== undefined)
+            data.hle_target_percent = request.hle_target_percent;
+        if (request.min_hle_score !== undefined)
+            data.min_hle_score = request.min_hle_score;
+        if (request.auto_select_by_hle !== undefined)
+            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');
+    }
     /**
      * Messages-first complete with intelligent model selection (POST /api/v2/complete).
      *
@@ -234,7 +342,9 @@ class PcompresslrAPIClient {
             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);
+        // Prefer async jobs for production reliability; sync remains available via /api/v2/complete
+        // by calling makeRequest directly if needed.
+        return this.completeAsync(request);
     }
 }
 exports.PcompresslrAPIClient = PcompresslrAPIClient;

package/dist/core.d.ts

@@ -19,10 +19,12 @@ export interface CompleteOptions {
     messages: Message[];
     model?: string;
     provider?: 'openai' | 'anthropic' | 'google';
+    desiredHle?: number;
     compress?: boolean;
     compressionConfig?: CompressionConfig;
     compressOutput?: boolean;
     useOptimal?: boolean;
+    mode?: 'async' | 'sync';
     hleTargetPercent?: number;
     minHleScore?: number;
     autoSelectByHle?: boolean;

package/dist/core.js

@@ -27,10 +27,10 @@ class LightReach {
             }
             : undefined;
         try {
-            const resp = await this.apiClient.complete({
+            const req = {
                 messages: options.messages,
-                model: options.model ?? this.defaultModel,
                 llm_provider: options.provider ?? this.defaultProvider,
+                desired_hle: options.desiredHle,
                 compress: options.compress ?? true,
                 compression_config: cfg,
                 compress_output: options.compressOutput ?? false,
@@ -43,7 +43,13 @@ class LightReach {
                 max_tokens: options.maxTokens,
                 tags: options.tags,
                 max_history_messages: options.maxHistoryMessages,
-            });
+            };
+            // Only include deprecated `model` if explicitly provided to avoid noisy warnings.
+            if (options.model !== undefined)
+                req.model = options.model;
+            const resp = (options.mode ?? 'async') === 'sync'
+                ? await this.apiClient.completeSync(req)
+                : await this.apiClient.complete(req);
             // 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 {

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compress-lightreach",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "AI cost management SDK with intelligent model routing, prompt compression, and real-time token tracking",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",