compress-lightreach 1.0.6 → 1.0.9

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/)
@@ -10,7 +10,7 @@ Compress Light Reach is a Node.js/TypeScript SDK that provides intelligent model
 
 ## Features
 
-- **Intelligent Model Routing**: Automatically selects optimal model based on quality requirements (HLE) and available provider keys
+- **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
@@ -37,7 +37,7 @@ 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 optimal model based on your requirements
+- System automatically selects the optimal model based on admin-configured quality settings
 
 ```typescript
 import { PcompresslrAPIClient } from 'compress-lightreach';
@@ -49,10 +49,10 @@ const result = await client.complete({
     { role: 'system', content: 'You are a helpful assistant.' },
     { role: 'user', content: 'Explain quantum computing in simple terms.' },
   ],
-  desired_hle: 30,  // Quality ceiling (0-100). Current SOTA is ~40%.
+  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}`);
 ```
@@ -61,15 +61,15 @@ console.log(`Token savings: ${result.compression_stats.token_savings}`);
 
 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://compress.lightreach.io/v1/cursor`
-- **Generic OpenAI-compatible base URL**: `https://compress.lightreach.io/v1`
+- **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):
 
 ```bash
-curl -sS https://compress.lightreach.io/v1/chat/completions \
+curl -sS https://api.compress.lightreach.io/v1/chat/completions \
   -H "Authorization: Bearer lr_your_lightreach_key" \
   -H "Content-Type: application/json" \
   -d '{
@@ -79,84 +79,95 @@ curl -sS https://compress.lightreach.io/v1/chat/completions \
   }'
 ```
 
-### With Output Compression
+## 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.
 
 ```typescript
 const result = await client.complete({
-  messages: [{ role: 'user', content: 'Generate a long report...' }],
-  desired_hle: 25,
-  compress_output: true,
+  messages: [{ role: 'user', content: 'Summarize this document...' }],
+  tags: {
+    team: 'backend',
+    environment: 'production',
+    feature: 'summarization',
+  },
 });
-
-console.log(result.decompressed_response);
 ```
 
-### Intelligent Model Routing
+> **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:
 
-The system automatically selects the optimal model based on quality requirements and your available provider keys:
+- **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.
 
 ```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' }],
-  desired_hle: 30,  // Quality ceiling (0-100). Current SOTA is ~40%.
+  tags: { team: 'backend', environment: 'production' },
 });
 
-// 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
 ```
 
+### Routing Response
+
+Every `complete()` response includes `routing_info` with full transparency into the routing decision:
+
+```typescript
+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:
 
 ```typescript
-// Only use OpenAI models, but pick the cheapest one meeting HLE 35
 const result = await client.complete({
   messages: [{ role: 'user', content: 'Write a poem' }],
-  llm_provider: 'openai',  // Optional: constrain to one provider
-  desired_hle: 35,
+  llm_provider: 'anthropic',
 });
 ```
 
-### 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; if it exceeds an admin-set ceiling, the request will **silently clamp** to the ceiling and proceed.
+### With Output Compression
 
 ```typescript
-// Admin set global HLE ceiling to 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({
-  messages: [{ role: 'user', content: 'Process payment' }],
-  desired_hle: 25,  // OK: below ceiling of 30
-  tags: { env: 'production' },
+  messages: [{ role: 'user', content: 'Generate a long report...' }],
+  compress_output: true,
 });
 
-// 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} ` +
-              `by ${result.routing_info.hle_source}-level ceiling`);
-}
+console.log(result.choices[0].message.content);
 ```
 
 ### With Compression Config
 
-Configure per-role compression settings:
+Control which message roles get compressed:
 
 ```typescript
 import { PcompresslrAPIClient } from 'compress-lightreach';
@@ -165,7 +176,6 @@ const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 const result = await client.complete({
   messages: [{ role: 'user', content: 'Hello!' }],
-  desired_hle: 30,
   compress: true,
   compress_output: false,
   compression_config: {
@@ -176,14 +186,13 @@ const result = await client.complete({
   },
   temperature: 0.7,
   max_tokens: 1000,
-  tags: { env: 'production' },
+  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
@@ -191,11 +200,10 @@ import { PcompresslrAPIClient } from 'compress-lightreach';
 
 const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
-// Compress text without making an LLM call
 const compressed = await client.compress(
   "Your text with repeated content here...",
-  "gpt-4",      // Model for tokenization
-  { env: 'dev' } // Optional tags
+  "gpt-4",
+  { team: 'backend' },
 );
 
 console.log(compressed.llm_format);
@@ -209,10 +217,8 @@ console.log(decompressed.decompressed);
 ### Command Line Interface
 
 ```bash
-# Set your API key
 export PCOMPRESLR_API_KEY=your-api-key
 
-# Compress a prompt
 npx pcompresslr "Your prompt with repeated text here..."
 ```
 
@@ -237,7 +243,9 @@ new PcompresslrAPIClient(apiKey?: string, apiUrl?: string, timeout?: number)
 
 ##### `complete(request: CompleteV2Request): Promise<CompleteResponse>`
 
-Messages-first completion with intelligent routing (POST `/api/v2/complete`).
+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`):**
 
@@ -245,13 +253,12 @@ 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 ceiling (0-100). 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 |
 | `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 tag-level HLE ceilings |
+| `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:**
@@ -269,7 +276,21 @@ Messages-first completion with intelligent routing (POST `/api/v2/complete`).
 
 ```typescript
 {
-  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;
@@ -293,33 +314,48 @@ Messages-first completion with intelligent routing (POST `/api/v2/complete`).
     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
+    model_hle: number;               // HLE score of selected model (server-computed)
     model_price_per_million: number;
-    requested_hle: number | null;
-    effective_hle: number | null;    // Effective HLE after admin ceilings
-    hle_source: 'request' | 'tag' | 'global' | 'none';
-    hle_clamped: boolean;            // true if admin ceiling lowered your desired_hle
+    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
-  text?: string;                     // Alias for decompressed_response
-  tokens_saved?: number;             // Alias for compression_stats.token_savings
-  tokens_used?: number;              // Alias for llm_stats.total_tokens
-  compression_ratio?: number;        // Alias for compression_stats.compression_ratio
+  tokens_saved?: number;
+  tokens_used?: number;
+  compression_ratio?: number;
+  cost_estimate?: number | null;
+  savings_estimate?: number | null;
 }
 ```
 
-##### `compress(prompt, model?, tags?): Promise<CompressResponse>`
+##### `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()`.
 
-Also supports a legacy call shape: `compress(prompt, model, algorithm, tags?)` (only `"greedy"` is supported).
+**Options:**
+- `pollIntervalMs` (number, default: 1000): Polling interval in milliseconds
+- `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'`
-- `algorithm` (`"greedy"`, optional): Legacy-only parameter. Only `"greedy"` is supported.
 - `tags` (`Record<string, string>`, optional): Tags for attribution
 
 **Response (`CompressResponse`):**
@@ -366,7 +402,6 @@ Check API health status (GET `/health`).
 }
 ```
 
-
 ### Message Types
 
 ```typescript
@@ -393,7 +428,7 @@ interface Message {
 | `PcompresslrAPIError` | Base exception class |
 | `APIKeyError` | Invalid or missing API key |
 | `RateLimitError` | Rate limit exceeded |
-| `APIRequestError` | General API errors (including routing failures) |
+| `APIRequestError` | General API errors (including routing failures, tag validation errors) |
 
 ```typescript
 import { APIKeyError, RateLimitError, APIRequestError } from 'compress-lightreach';
@@ -413,15 +448,10 @@ try {
 
 ## How It Works
 
-Compress Light Reach uses intelligent algorithms to identify repeated substrings in your prompts and replace them with shorter placeholders.
-
-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. Intelligently routes to the best model based on your quality requirements
-5. Formats the result for easy LLM consumption
-6. Provides perfect decompression
+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
 
 ## Examples
 
@@ -440,10 +470,10 @@ Write a story about a bird. The bird is very friendly.
 
 const result = await client.complete({
   messages: [{ role: "user", content: prompt }],
-  desired_hle: 30,
+  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)}%`);
@@ -458,11 +488,10 @@ const client = new PcompresslrAPIClient("your-lightreach-api-key");
 
 const result = await client.complete({
   messages: [{ role: "user", content: "Generate a long report with repeated sections..." }],
-  desired_hle: 35,
   compress_output: true,
 });
 
-console.log(result.decompressed_response);
+console.log(result.choices[0].message.content);
 ```
 
 ### Example 3: Multi-turn Conversation
@@ -479,13 +508,13 @@ const result = await client.complete({
     { role: "assistant", content: "You can use open() with a context manager..." },
     { role: "user", content: "How about writing to a file?" },
   ],
-  desired_hle: 30,
   compression_config: {
     compress_system: false,
     compress_user: true,
     compress_assistant: false,
-    compress_only_last_n_user: 2,  // Only compress last 2 user messages
+    compress_only_last_n_user: 2,
   },
+  tags: { team: 'engineering', feature: 'code-assistant' },
 });
 ```
 

package/dist/api-client.d.ts

@@ -28,7 +28,27 @@ export interface DecompressResponse {
     processing_time_ms: number;
 }
 export interface CompleteResponse {
-    decompressed_response: string;
+    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;
@@ -53,19 +73,29 @@ export interface CompleteResponse {
         selected_model: string;
         selected_provider: string;
         selected_model_id: string;
+        /** HLE score of the selected model (server-computed). */
         model_hle: number;
         model_price_per_million: number;
-        requested_hle: number | null;
+        input_price_per_million?: number | null;
+        output_price_per_million?: number | null;
+        /** @deprecated Present for backward compatibility. */
+        requested_hle?: number | null;
+        /** The quality ceiling that was applied (from global, tag, or integration settings). */
         effective_hle: number | null;
+        /** Where the effective HLE ceiling came from. */
         hle_source: 'request' | 'tag' | 'global' | 'none';
-        hle_clamped: boolean;
+        /** @deprecated Present for backward compatibility. */
+        hle_clamped?: boolean;
     };
-    text?: string;
     tokens_saved?: number;
     tokens_used?: number;
     compression_ratio?: number;
     cost_estimate?: number | null;
     savings_estimate?: number | null;
+    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 {
@@ -74,7 +104,13 @@ export interface Message {
 }
 export interface CompleteV2Request {
     messages: Message[];
+    /** Optional provider constraint. Omit for cross-provider cost optimization. */
     llm_provider?: 'openai' | 'anthropic' | 'google' | 'deepseek' | 'moonshot';
+    /**
+     * @deprecated Quality routing is now fully managed by admin-configured ceilings
+     * (global, tag-level, integration-level) in the dashboard. This parameter is
+     * accepted for backward compatibility but should not be used in new code.
+     */
     desired_hle?: number;
     compress?: boolean;
     compression_config?: {
@@ -87,12 +123,25 @@ export interface CompleteV2Request {
     algorithm?: 'greedy';
     temperature?: number;
     max_tokens?: number;
+    /**
+     * Tags for cost attribution and tag-level quality ceilings.
+     * Supported keys: 'team', 'environment', 'feature'.
+     * Values are validated server-side against your workspace's allowed list.
+     * The 'integration' tag is reserved for system use and should not be set manually.
+     *
+     * @example { team: 'backend', environment: 'production', feature: 'search' }
+     */
     tags?: Record<string, string>;
     max_history_messages?: number;
+    /** @deprecated System selects model automatically. */
     model?: string;
+    /** @deprecated Use desired_hle instead. */
     hle_target_percent?: number;
+    /** @deprecated Use desired_hle instead. */
     min_hle_score?: number;
+    /** @deprecated Always auto-selects now. */
     auto_select_by_hle?: boolean;
+    /** @deprecated Use llm_provider instead. */
     same_provider_only?: boolean;
 }
 export interface HealthCheckResponse {
@@ -124,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).
      */
@@ -145,9 +195,11 @@ export declare class PcompresslrAPIClient {
     /**
      * Compress text without making an LLM call (POST /api/v1/compress).
      *
-     * Supported call shapes:
-     * - compress(prompt, model?, tags?)
-     * - compress(prompt, model, algorithm, tags?)  (back-compat; only "greedy" is supported)
+     * @param prompt - Text to compress
+     * @param model - Model for tokenization (default: 'gpt-4')
+     * @param tags - Tags for attribution. Supported keys: 'team', 'environment', 'feature'.
+     *
+     * Also supports a legacy call shape: compress(prompt, model, 'greedy', tags?)
      */
     compress(prompt: string, model?: string, tags?: Record<string, string>): Promise<CompressResponse>;
     compress(prompt: string, model: string, algorithm: 'greedy', tags?: Record<string, string>): Promise<CompressResponse>;
@@ -161,32 +213,23 @@ export declare class PcompresslrAPIClient {
      */
     completeSync(request: CompleteV2Request): Promise<CompleteResponse>;
     /**
-     * Messages-first complete with intelligent model selection (POST /api/v2/complete).
+     * Messages-first complete with intelligent model selection.
      *
-     * v1.0.0: System automatically selects optimal model based on your provider keys,
-     * desired HLE, and admin's global/tag-level HLE ceilings.
+     * Uses async job processing (enqueue + poll) for production reliability.
+     * Model routing is managed by admin-configured quality ceilings (global,
+     * tag-level, integration-level) in the dashboard. The system selects the
+     * cheapest model that meets the effective ceiling.
      *
      * 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,
+     *   tags: { team: 'backend', environment: 'production' },
      * });
      *
-     * // Access routing info
      * console.log(response.routing_info?.selected_model);
-     * if (response.routing_info?.hle_clamped) {
-     *   console.log('Admin ceiling lowered your desired HLE');
-     * }
+     * console.log(response.routing_info?.effective_hle);
      */
     complete(request: CompleteV2Request): Promise<CompleteResponse>;
 }

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,35 +344,27 @@ 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 (POST /api/v2/complete).
+     * Messages-first complete with intelligent model selection.
      *
-     * v1.0.0: System automatically selects optimal model based on your provider keys,
-     * desired HLE, and admin's global/tag-level HLE ceilings.
+     * Uses async job processing (enqueue + poll) for production reliability.
+     * Model routing is managed by admin-configured quality ceilings (global,
+     * tag-level, integration-level) in the dashboard. The system selects the
+     * cheapest model that meets the effective ceiling.
      *
      * 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,
+     *   tags: { team: 'backend', environment: 'production' },
      * });
      *
-     * // Access routing info
      * console.log(response.routing_info?.selected_model);
-     * if (response.routing_info?.hle_clamped) {
-     *   console.log('Admin ceiling lowered your desired HLE');
-     * }
+     * console.log(response.routing_info?.effective_hle);
      */
     async complete(request) {
         // Warn about deprecated parameters

package/dist/core.d.ts

@@ -17,19 +17,33 @@ export interface CompressionConfig {
 }
 export interface CompleteOptions {
     messages: Message[];
+    /** @deprecated System selects model automatically. */
     model?: string;
     provider?: 'openai' | 'anthropic' | 'google';
+    /**
+     * @deprecated Quality routing is now fully managed by admin-configured ceilings
+     * in the dashboard. Accepted for backward compatibility.
+     */
     desiredHle?: number;
     compress?: boolean;
     compressionConfig?: CompressionConfig;
     compressOutput?: boolean;
     mode?: 'async' | 'sync';
+    /** @deprecated Use desiredHle instead. */
     hleTargetPercent?: number;
+    /** @deprecated Use desiredHle instead. */
     minHleScore?: number;
+    /** @deprecated Always auto-selects now. */
     autoSelectByHle?: boolean;
+    /** @deprecated Use provider instead. */
     sameProviderOnly?: boolean;
     temperature?: number;
     maxTokens?: number;
+    /**
+     * Tags for cost attribution and quality ceilings.
+     * Supported keys: 'team', 'environment', 'feature'.
+     * The 'integration' tag is reserved for system use.
+     */
     tags?: Record<string, string>;
     maxHistoryMessages?: number;
 }

package/dist/core.js

@@ -51,7 +51,6 @@ class LightReach {
             // 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,

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.6",
-  "description": "AI cost management SDK with intelligent model routing, prompt compression, and real-time token tracking",
+  "version": "1.0.9",
+  "description": "OpenAI-compatible LLM routing and compression SDK with LightReach metadata extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {