@compresr/sdk 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/README.md +263 -0
  2. package/dist/cjs/clients/compression.d.ts +137 -0
  3. package/dist/cjs/clients/compression.d.ts.map +1 -0
  4. package/dist/cjs/clients/compression.js +220 -0
  5. package/dist/cjs/clients/compression.js.map +1 -0
  6. package/dist/cjs/clients/index.d.ts +2 -0
  7. package/dist/cjs/clients/index.d.ts.map +1 -0
  8. package/dist/cjs/clients/index.js +6 -0
  9. package/dist/cjs/clients/index.js.map +1 -0
  10. package/dist/cjs/config/constants.d.ts +61 -0
  11. package/dist/cjs/config/constants.d.ts.map +1 -0
  12. package/dist/cjs/config/constants.js +77 -0
  13. package/dist/cjs/config/constants.js.map +1 -0
  14. package/dist/cjs/config/endpoints.d.ts +18 -0
  15. package/dist/cjs/config/endpoints.d.ts.map +1 -0
  16. package/dist/cjs/config/endpoints.js +25 -0
  17. package/dist/cjs/config/endpoints.js.map +1 -0
  18. package/dist/cjs/config/index.d.ts +3 -0
  19. package/dist/cjs/config/index.d.ts.map +1 -0
  20. package/dist/cjs/config/index.js +20 -0
  21. package/dist/cjs/config/index.js.map +1 -0
  22. package/dist/cjs/errors/exceptions.d.ts +72 -0
  23. package/dist/cjs/errors/exceptions.d.ts.map +1 -0
  24. package/dist/cjs/errors/exceptions.js +107 -0
  25. package/dist/cjs/errors/exceptions.js.map +1 -0
  26. package/dist/cjs/errors/index.d.ts +2 -0
  27. package/dist/cjs/errors/index.d.ts.map +1 -0
  28. package/dist/cjs/errors/index.js +13 -0
  29. package/dist/cjs/errors/index.js.map +1 -0
  30. package/dist/cjs/http/client.d.ts +53 -0
  31. package/dist/cjs/http/client.d.ts.map +1 -0
  32. package/dist/cjs/http/client.js +268 -0
  33. package/dist/cjs/http/client.js.map +1 -0
  34. package/dist/cjs/http/errors.d.ts +19 -0
  35. package/dist/cjs/http/errors.d.ts.map +1 -0
  36. package/dist/cjs/http/errors.js +87 -0
  37. package/dist/cjs/http/errors.js.map +1 -0
  38. package/dist/cjs/http/index.d.ts +3 -0
  39. package/dist/cjs/http/index.d.ts.map +1 -0
  40. package/dist/cjs/http/index.js +8 -0
  41. package/dist/cjs/http/index.js.map +1 -0
  42. package/dist/cjs/index.d.ts +33 -0
  43. package/dist/cjs/index.d.ts.map +1 -0
  44. package/dist/cjs/index.js +49 -0
  45. package/dist/cjs/index.js.map +1 -0
  46. package/dist/cjs/package.json +1 -0
  47. package/dist/cjs/schemas/common.d.ts +47 -0
  48. package/dist/cjs/schemas/common.d.ts.map +1 -0
  49. package/dist/cjs/schemas/common.js +29 -0
  50. package/dist/cjs/schemas/common.js.map +1 -0
  51. package/dist/cjs/schemas/compression.d.ts +378 -0
  52. package/dist/cjs/schemas/compression.d.ts.map +1 -0
  53. package/dist/cjs/schemas/compression.js +99 -0
  54. package/dist/cjs/schemas/compression.js.map +1 -0
  55. package/dist/cjs/schemas/index.d.ts +7 -0
  56. package/dist/cjs/schemas/index.d.ts.map +1 -0
  57. package/dist/cjs/schemas/index.js +30 -0
  58. package/dist/cjs/schemas/index.js.map +1 -0
  59. package/dist/cjs/schemas/search.d.ts +184 -0
  60. package/dist/cjs/schemas/search.d.ts.map +1 -0
  61. package/dist/cjs/schemas/search.js +75 -0
  62. package/dist/cjs/schemas/search.js.map +1 -0
  63. package/dist/esm/clients/compression.d.ts +137 -0
  64. package/dist/esm/clients/compression.d.ts.map +1 -0
  65. package/dist/esm/clients/compression.js +216 -0
  66. package/dist/esm/clients/compression.js.map +1 -0
  67. package/dist/esm/clients/index.d.ts +2 -0
  68. package/dist/esm/clients/index.d.ts.map +1 -0
  69. package/dist/esm/clients/index.js +2 -0
  70. package/dist/esm/clients/index.js.map +1 -0
  71. package/dist/esm/config/constants.d.ts +61 -0
  72. package/dist/esm/config/constants.d.ts.map +1 -0
  73. package/dist/esm/config/constants.js +74 -0
  74. package/dist/esm/config/constants.js.map +1 -0
  75. package/dist/esm/config/endpoints.d.ts +18 -0
  76. package/dist/esm/config/endpoints.d.ts.map +1 -0
  77. package/dist/esm/config/endpoints.js +22 -0
  78. package/dist/esm/config/endpoints.js.map +1 -0
  79. package/dist/esm/config/index.d.ts +3 -0
  80. package/dist/esm/config/index.d.ts.map +1 -0
  81. package/dist/esm/config/index.js +3 -0
  82. package/dist/esm/config/index.js.map +1 -0
  83. package/dist/esm/errors/exceptions.d.ts +72 -0
  84. package/dist/esm/errors/exceptions.d.ts.map +1 -0
  85. package/dist/esm/errors/exceptions.js +96 -0
  86. package/dist/esm/errors/exceptions.js.map +1 -0
  87. package/dist/esm/errors/index.d.ts +2 -0
  88. package/dist/esm/errors/index.d.ts.map +1 -0
  89. package/dist/esm/errors/index.js +2 -0
  90. package/dist/esm/errors/index.js.map +1 -0
  91. package/dist/esm/http/client.d.ts +53 -0
  92. package/dist/esm/http/client.d.ts.map +1 -0
  93. package/dist/esm/http/client.js +264 -0
  94. package/dist/esm/http/client.js.map +1 -0
  95. package/dist/esm/http/errors.d.ts +19 -0
  96. package/dist/esm/http/errors.d.ts.map +1 -0
  97. package/dist/esm/http/errors.js +84 -0
  98. package/dist/esm/http/errors.js.map +1 -0
  99. package/dist/esm/http/index.d.ts +3 -0
  100. package/dist/esm/http/index.d.ts.map +1 -0
  101. package/dist/esm/http/index.js +3 -0
  102. package/dist/esm/http/index.js.map +1 -0
  103. package/dist/esm/index.d.ts +33 -0
  104. package/dist/esm/index.d.ts.map +1 -0
  105. package/dist/esm/index.js +36 -0
  106. package/dist/esm/index.js.map +1 -0
  107. package/dist/esm/schemas/common.d.ts +47 -0
  108. package/dist/esm/schemas/common.d.ts.map +1 -0
  109. package/dist/esm/schemas/common.js +26 -0
  110. package/dist/esm/schemas/common.js.map +1 -0
  111. package/dist/esm/schemas/compression.d.ts +378 -0
  112. package/dist/esm/schemas/compression.d.ts.map +1 -0
  113. package/dist/esm/schemas/compression.js +96 -0
  114. package/dist/esm/schemas/compression.js.map +1 -0
  115. package/dist/esm/schemas/index.d.ts +7 -0
  116. package/dist/esm/schemas/index.d.ts.map +1 -0
  117. package/dist/esm/schemas/index.js +10 -0
  118. package/dist/esm/schemas/index.js.map +1 -0
  119. package/dist/esm/schemas/search.d.ts +184 -0
  120. package/dist/esm/schemas/search.d.ts.map +1 -0
  121. package/dist/esm/schemas/search.js +72 -0
  122. package/dist/esm/schemas/search.js.map +1 -0
  123. package/package.json +86 -0
package/README.md ADDED
@@ -0,0 +1,263 @@
1
+ # Compresr TypeScript SDK
2
+
3
+ [![npm](https://img.shields.io/npm/v/compresr)](https://www.npmjs.com/package/compresr)
4
+ [![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D5.0-blue)](https://www.typescriptlang.org/)
5
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
6
+
7
+ Official TypeScript SDK for [Compresr](https://compresr.ai) - Intelligent context compression to reduce LLM API costs by 30-70%.
8
+
9
+ ## Installation
10
+
11
+ ```bash
12
+ npm install compresr
13
+ # or
14
+ yarn add compresr
15
+ # or
16
+ pnpm add compresr
17
+ ```
18
+
19
+ ## Quick Start
20
+
21
+ ### API Key Setup
22
+
23
+ Get your API key from [compresr.ai](https://compresr.ai):
24
+
25
+ 1. Create an account at [compresr.ai](https://compresr.ai)
26
+ 2. Navigate to Dashboard → API Keys
27
+ 3. Click "Create New Key" and copy it (shown only once!)
28
+
29
+ ### Basic Usage
30
+
31
+ ```typescript
32
+ import { CompressionClient } from 'compresr';
33
+
34
+ const client = new CompressionClient({ apiKey: 'cmp_your_api_key' });
35
+
36
+ // Agnostic compression (espresso_v1) — no query needed
37
+ const result = await client.compress({
38
+ context: 'Your very long context that needs compression...',
39
+ });
40
+
41
+ console.log(`Original: ${result.data.original_tokens} tokens`);
42
+ console.log(`Compressed: ${result.data.compressed_tokens} tokens`);
43
+ console.log(`Saved: ${result.data.tokens_saved} tokens`);
44
+ ```
45
+
46
+ ### Query-Specific Compression
47
+
48
+ ```typescript
49
+ // Query-specific compression (latte_v1) — query REQUIRED
50
+ const result = await client.compress({
51
+ context: 'Python was created in 1991. JavaScript in 1995. Java in 1995.',
52
+ query: 'Who created Python?',
53
+ compressionModelName: 'latte_v1',
54
+ });
55
+
56
+ console.log(result.data.compressed_context);
57
+ // Output preserves Python-relevant content
58
+ ```
59
+
60
+ ## Compression Models
61
+
62
+ | Model | Query | Description |
63
+ |-------|-------|-------------|
64
+ | `espresso_v1` | Not needed | Agnostic compression — good for system prompts, documents |
65
+ | `latte_v1` | **Required** | Query-specific — preserves tokens relevant to your question |
66
+
67
+ ## API Reference
68
+
69
+ ### `CompressionClient`
70
+
71
+ ```typescript
72
+ import { CompressionClient } from 'compresr';
73
+
74
+ const client = new CompressionClient({
75
+ apiKey: 'cmp_your_api_key', // Required
76
+ timeout: 60000, // Optional: request timeout in ms (default: 60000)
77
+ baseUrl: 'https://api.compresr.ai', // Optional: override API URL
78
+ });
79
+ ```
80
+
81
+ ### Methods
82
+
83
+ #### `compress(options): Promise<CompressResponse>`
84
+
85
+ Compress context text.
86
+
87
+ ```typescript
88
+ const result = await client.compress({
89
+ context: 'Your context...', // Required: string or string[]
90
+ compressionModelName: 'espresso_v1', // Optional (default: 'espresso_v1')
91
+ query: 'Your question?', // Required for latte_v1
92
+ targetCompressionRatio: 0.5, // Optional: 0-1 or >1 for Nx
93
+ coarse: false, // Optional: paragraph-level (latte_v1 only)
94
+ });
95
+ ```
96
+
97
+ #### `compressStream(options): AsyncGenerator<StreamChunk>`
98
+
99
+ Stream compression chunks in real-time.
100
+
101
+ ```typescript
102
+ for await (const chunk of client.compressStream({
103
+ context: 'Your context...',
104
+ })) {
105
+ if (!chunk.done) {
106
+ process.stdout.write(chunk.content);
107
+ }
108
+ }
109
+ ```
110
+
111
+ #### `compressBatch(options): Promise<CompressBatchResponse>`
112
+
113
+ Batch compress multiple contexts (more efficient than multiple `compress()` calls).
114
+
115
+ ```typescript
116
+ // Same query for all contexts
117
+ const result = await client.compressBatch({
118
+ contexts: ['Doc 1...', 'Doc 2...', 'Doc 3...'],
119
+ queries: 'What are the key points?',
120
+ compressionModelName: 'latte_v1', // Optional (default for batch)
121
+ });
122
+
123
+ // Different query per context
124
+ const result = await client.compressBatch({
125
+ contexts: ['ML doc...', 'NLP doc...'],
126
+ queries: ['What is ML?', 'What is NLP?'],
127
+ });
128
+
129
+ console.log(`Total saved: ${result.data.total_tokens_saved} tokens`);
130
+ ```
131
+
132
+ ## Response Types
133
+
134
+ ### CompressResponse
135
+
136
+ ```typescript
137
+ interface CompressResponse {
138
+ success: boolean;
139
+ data: {
140
+ original_context: string | string[];
141
+ compressed_context: string | string[];
142
+ original_tokens: number;
143
+ compressed_tokens: number;
144
+ actual_compression_ratio: number;
145
+ tokens_saved: number;
146
+ duration_ms: number;
147
+ } | null;
148
+ }
149
+ ```
150
+
151
+ ### CompressBatchResponse
152
+
153
+ ```typescript
154
+ interface CompressBatchResponse {
155
+ success: boolean;
156
+ data: {
157
+ results: CompressBatchItemResult[];
158
+ total_original_tokens: number;
159
+ total_compressed_tokens: number;
160
+ total_tokens_saved: number;
161
+ average_compression_ratio: number;
162
+ count: number;
163
+ } | null;
164
+ }
165
+ ```
166
+
167
+ ## Integration with OpenAI
168
+
169
+ ```typescript
170
+ import { CompressionClient } from 'compresr';
171
+ import OpenAI from 'openai';
172
+
173
+ const compresr = new CompressionClient({ apiKey: 'cmp_xxx' });
174
+ const openai = new OpenAI({ apiKey: 'sk-xxx' });
175
+
176
+ // Compress your context first
177
+ const compressed = await compresr.compress({
178
+ context: 'Your very long system prompt or document...',
179
+ });
180
+
181
+ // Use compressed context with OpenAI
182
+ const response = await openai.chat.completions.create({
183
+ model: 'gpt-4o',
184
+ messages: [
185
+ { role: 'system', content: compressed.data.compressed_context },
186
+ { role: 'user', content: 'Analyze this data...' },
187
+ ],
188
+ });
189
+
190
+ console.log(`Saved ${compressed.data.tokens_saved} tokens!`);
191
+ ```
192
+
193
+ ## Error Handling
194
+
195
+ ```typescript
196
+ import {
197
+ CompressionClient,
198
+ CompresrError,
199
+ AuthenticationError,
200
+ ValidationError,
201
+ RateLimitError,
202
+ } from 'compresr';
203
+
204
+ try {
205
+ const result = await client.compress({ context: 'Hello' });
206
+ } catch (error) {
207
+ if (error instanceof AuthenticationError) {
208
+ console.error('Invalid API key:', error.message);
209
+ } else if (error instanceof ValidationError) {
210
+ console.error('Invalid request:', error.message, 'Field:', error.field);
211
+ } else if (error instanceof RateLimitError) {
212
+ console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
213
+ } else if (error instanceof CompresrError) {
214
+ console.error('API error:', error.message, 'Code:', error.code);
215
+ }
216
+ }
217
+ ```
218
+
219
+ ### Error Types
220
+
221
+ | Error | Description |
222
+ |-------|-------------|
223
+ | `AuthenticationError` | Invalid or missing API key |
224
+ | `ValidationError` | Invalid request parameters |
225
+ | `RateLimitError` | Too many requests (includes `retryAfter`) |
226
+ | `ScopeError` | API key lacks required permissions |
227
+ | `ServerError` | Internal server error |
228
+ | `ConnectionError` | Network/connection failure |
229
+ | `NotFoundError` | Resource not found |
230
+
231
+ ## Requirements
232
+
233
+ - Node.js 18+ (uses native `fetch`)
234
+ - TypeScript 5.0+ (optional, but recommended)
235
+
236
+ ## Development
237
+
238
+ ```bash
239
+ # Install dependencies
240
+ npm install
241
+
242
+ # Run unit tests
243
+ npm test
244
+
245
+ # Run integration tests (requires COMPRESR_API_KEY)
246
+ npm run test:integration
247
+
248
+ # Build
249
+ npm run build
250
+
251
+ # Lint
252
+ npm run lint
253
+ ```
254
+
255
+ ## Support
256
+
257
+ - Email: support@compresr.ai
258
+ - [API Documentation](https://compresr.ai/docs)
259
+ - [GitHub Issues](https://github.com/compresr/sdk/issues)
260
+
261
+ ## License
262
+
263
+ Apache 2.0 License - see [LICENSE](LICENSE) for details.
@@ -0,0 +1,137 @@
1
+ import { type HttpClientOptions } from '../http/client.js';
2
+ import { type CompressResponse, type CompressBatchResponse, type StreamChunk } from '../schemas/index.js';
3
+ /**
4
+ * Options for single compression
5
+ */
6
+ export interface CompressOptions {
7
+ /** Context to compress - single string or array of strings */
8
+ context: string | string[];
9
+ /** Compression model (default: espresso_v1) */
10
+ compressionModelName?: string;
11
+ /** Query for query-specific models (required for latte_v1) */
12
+ query?: string;
13
+ /**
14
+ * Target compression ratio:
15
+ * - 0-1: percentage to keep (e.g., 0.5 = keep 50%)
16
+ * - >1: Nx factor (e.g., 4 = 4x compression = keep 25%)
17
+ */
18
+ targetCompressionRatio?: number;
19
+ /** Use paragraph-level compression (faster, latte_v1 only) */
20
+ coarse?: boolean;
21
+ }
22
+ /**
23
+ * Options for batch compression
24
+ */
25
+ export interface CompressBatchOptions {
26
+ /** List of contexts to compress (1-100 items) */
27
+ contexts: string[];
28
+ /** Single query for all contexts, or one query per context */
29
+ queries: string | string[];
30
+ /** Compression model (default: latte_v1 for batch) */
31
+ compressionModelName?: string;
32
+ /** Target compression ratio */
33
+ targetCompressionRatio?: number;
34
+ /** Use paragraph-level compression (faster) */
35
+ coarse?: boolean;
36
+ }
37
+ /**
38
+ * Token-level compression client
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * import { CompressionClient } from 'compresr';
43
+ *
44
+ * const client = new CompressionClient({ apiKey: 'cmp_...' });
45
+ *
46
+ * // Agnostic compression
47
+ * const result = await client.compress({
48
+ * context: 'Your long context...',
49
+ * });
50
+ *
51
+ * // Query-specific compression
52
+ * const result = await client.compress({
53
+ * context: 'Your long context...',
54
+ * query: 'What is the main conclusion?',
55
+ * compressionModelName: 'latte_v1',
56
+ * });
57
+ * ```
58
+ */
59
+ export declare class CompressionClient {
60
+ private readonly http;
61
+ constructor(options: HttpClientOptions);
62
+ /**
63
+ * Validate that the model is allowed
64
+ */
65
+ private validateModel;
66
+ /**
67
+ * Validate query parameter against model requirements
68
+ */
69
+ private validateQueryForModel;
70
+ /**
71
+ * Resolve endpoints based on model name
72
+ */
73
+ private resolveEndpoints;
74
+ /**
75
+ * Build request payload
76
+ */
77
+ private buildRequest;
78
+ /**
79
+ * Compress context (async)
80
+ *
81
+ * @example
82
+ * ```typescript
83
+ * // Agnostic compression (espresso_v1)
84
+ * const result = await client.compress({
85
+ * context: 'Your long context text...',
86
+ * });
87
+ *
88
+ * // Query-specific compression (latte_v1)
89
+ * const result = await client.compress({
90
+ * context: 'Your long context text...',
91
+ * query: 'What is the main conclusion?',
92
+ * compressionModelName: 'latte_v1',
93
+ * });
94
+ *
95
+ * console.log(`Saved ${result.data.tokens_saved} tokens!`);
96
+ * ```
97
+ */
98
+ compress(options: CompressOptions): Promise<CompressResponse>;
99
+ /**
100
+ * Stream compression chunks
101
+ *
102
+ * @example
103
+ * ```typescript
104
+ * for await (const chunk of client.compressStream({
105
+ * context: 'Your long context...',
106
+ * })) {
107
+ * process.stdout.write(chunk.content);
108
+ * }
109
+ * ```
110
+ */
111
+ compressStream(options: CompressOptions): AsyncGenerator<StreamChunk, void, undefined>;
112
+ /**
113
+ * Batch compress multiple contexts
114
+ *
115
+ * More efficient than calling compress() multiple times.
116
+ * Only supports query-specific models (latte_v1).
117
+ *
118
+ * @example
119
+ * ```typescript
120
+ * // Same query for all contexts
121
+ * const result = await client.compressBatch({
122
+ * contexts: ['Doc 1...', 'Doc 2...', 'Doc 3...'],
123
+ * queries: 'What are the key points?',
124
+ * });
125
+ *
126
+ * // Different query per context
127
+ * const result = await client.compressBatch({
128
+ * contexts: ['ML doc...', 'NLP doc...'],
129
+ * queries: ['What is ML?', 'What is NLP?'],
130
+ * });
131
+ *
132
+ * console.log(`Saved ${result.data.total_tokens_saved} tokens!`);
133
+ * ```
134
+ */
135
+ compressBatch(options: CompressBatchOptions): Promise<CompressBatchResponse>;
136
+ }
137
+ //# sourceMappingURL=compression.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../../src/clients/compression.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,+CAA+C;IAC/C,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,sDAAsD;IACtD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+BAA+B;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,OAAO,EAAE,iBAAiB;IAItC;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,OAAO,CAAC,YAAY;IA+BpB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IASnE;;;;;;;;;;;OAWG;IACI,cAAc,CACnB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC;IAW/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,aAAa,CACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,qBAAqB,CAAC;CAsDlC"}
@@ -0,0 +1,220 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CompressionClient = void 0;
4
+ /**
5
+ * CompressionClient - Token-level context compression
6
+ *
7
+ * Compresses context text to reduce token count before sending to LLMs.
8
+ * Supports both agnostic (no query) and query-specific compression.
9
+ *
10
+ * Models:
11
+ * - espresso_v1 (default): Agnostic compression, no query needed
12
+ * - latte_v1: Query-specific compression, query REQUIRED
13
+ */
14
+ const zod_1 = require("zod");
15
+ const index_js_1 = require("../config/index.js");
16
+ const index_js_2 = require("../errors/index.js");
17
+ const client_js_1 = require("../http/client.js");
18
+ const index_js_3 = require("../schemas/index.js");
19
+ /**
20
+ * Token-level compression client
21
+ *
22
+ * @example
23
+ * ```typescript
24
+ * import { CompressionClient } from 'compresr';
25
+ *
26
+ * const client = new CompressionClient({ apiKey: 'cmp_...' });
27
+ *
28
+ * // Agnostic compression
29
+ * const result = await client.compress({
30
+ * context: 'Your long context...',
31
+ * });
32
+ *
33
+ * // Query-specific compression
34
+ * const result = await client.compress({
35
+ * context: 'Your long context...',
36
+ * query: 'What is the main conclusion?',
37
+ * compressionModelName: 'latte_v1',
38
+ * });
39
+ * ```
40
+ */
41
+ class CompressionClient {
42
+ http;
43
+ constructor(options) {
44
+ this.http = new client_js_1.HttpClient(options);
45
+ }
46
+ /**
47
+ * Validate that the model is allowed
48
+ */
49
+ validateModel(modelName) {
50
+ if (!index_js_1.ALLOWED_COMPRESSION_MODELS.has(modelName)) {
51
+ const allowed = Array.from(index_js_1.ALLOWED_COMPRESSION_MODELS).join(', ');
52
+ throw new index_js_2.ValidationError(`Model '${modelName}' is not valid for CompressionClient. Allowed: ${allowed}`);
53
+ }
54
+ }
55
+ /**
56
+ * Validate query parameter against model requirements
57
+ */
58
+ validateQueryForModel(modelName, query) {
59
+ if (index_js_1.QUERY_REQUIRED_MODELS.has(modelName) && !query) {
60
+ throw new index_js_2.ValidationError(`Model '${modelName}' requires a 'query' parameter.`);
61
+ }
62
+ if (!index_js_1.QUERY_REQUIRED_MODELS.has(modelName) && query !== undefined) {
63
+ throw new index_js_2.ValidationError(`Model '${modelName}' does not accept a 'query' parameter. ` +
64
+ `Remove the query or use 'latte_v1' for query-specific compression.`);
65
+ }
66
+ }
67
+ /**
68
+ * Resolve endpoints based on model name
69
+ */
70
+ resolveEndpoints(modelName) {
71
+ if (index_js_1.AGNOSTIC_ENDPOINT_MODELS.has(modelName)) {
72
+ return {
73
+ base: index_js_1.ENDPOINTS.COMPRESS_AGNOSTIC,
74
+ stream: index_js_1.ENDPOINTS.COMPRESS_AGNOSTIC_STREAM,
75
+ };
76
+ }
77
+ return {
78
+ base: index_js_1.ENDPOINTS.COMPRESS_QS,
79
+ stream: index_js_1.ENDPOINTS.COMPRESS_QS_STREAM,
80
+ };
81
+ }
82
+ /**
83
+ * Build request payload
84
+ */
85
+ buildRequest(options) {
86
+ const modelName = options.compressionModelName ?? index_js_1.MODELS.ESPRESSO;
87
+ this.validateModel(modelName);
88
+ this.validateQueryForModel(modelName, options.query);
89
+ try {
90
+ const request = index_js_3.CompressRequestSchema.parse({
91
+ context: options.context,
92
+ compression_model_name: modelName,
93
+ query: options.query,
94
+ target_compression_ratio: options.targetCompressionRatio,
95
+ coarse: options.coarse,
96
+ });
97
+ return request;
98
+ }
99
+ catch (error) {
100
+ if (error instanceof zod_1.ZodError) {
101
+ const firstError = error.errors[0];
102
+ throw new index_js_2.ValidationError(firstError?.message ?? 'Validation failed', firstError?.path.join('.'));
103
+ }
104
+ throw error;
105
+ }
106
+ }
107
+ // ==========================================================================
108
+ // Public Methods
109
+ // ==========================================================================
110
+ /**
111
+ * Compress context (async)
112
+ *
113
+ * @example
114
+ * ```typescript
115
+ * // Agnostic compression (espresso_v1)
116
+ * const result = await client.compress({
117
+ * context: 'Your long context text...',
118
+ * });
119
+ *
120
+ * // Query-specific compression (latte_v1)
121
+ * const result = await client.compress({
122
+ * context: 'Your long context text...',
123
+ * query: 'What is the main conclusion?',
124
+ * compressionModelName: 'latte_v1',
125
+ * });
126
+ *
127
+ * console.log(`Saved ${result.data.tokens_saved} tokens!`);
128
+ * ```
129
+ */
130
+ async compress(options) {
131
+ const modelName = options.compressionModelName ?? index_js_1.MODELS.ESPRESSO;
132
+ const request = this.buildRequest(options);
133
+ const { base } = this.resolveEndpoints(modelName);
134
+ const response = await this.http.post(base, request);
135
+ return index_js_3.CompressResponseSchema.parse(response);
136
+ }
137
+ /**
138
+ * Stream compression chunks
139
+ *
140
+ * @example
141
+ * ```typescript
142
+ * for await (const chunk of client.compressStream({
143
+ * context: 'Your long context...',
144
+ * })) {
145
+ * process.stdout.write(chunk.content);
146
+ * }
147
+ * ```
148
+ */
149
+ async *compressStream(options) {
150
+ const modelName = options.compressionModelName ?? index_js_1.MODELS.ESPRESSO;
151
+ const request = this.buildRequest(options);
152
+ const { stream } = this.resolveEndpoints(modelName);
153
+ for await (const content of this.http.stream(stream, request)) {
154
+ yield { content, done: false };
155
+ }
156
+ yield { content: '', done: true };
157
+ }
158
+ /**
159
+ * Batch compress multiple contexts
160
+ *
161
+ * More efficient than calling compress() multiple times.
162
+ * Only supports query-specific models (latte_v1).
163
+ *
164
+ * @example
165
+ * ```typescript
166
+ * // Same query for all contexts
167
+ * const result = await client.compressBatch({
168
+ * contexts: ['Doc 1...', 'Doc 2...', 'Doc 3...'],
169
+ * queries: 'What are the key points?',
170
+ * });
171
+ *
172
+ * // Different query per context
173
+ * const result = await client.compressBatch({
174
+ * contexts: ['ML doc...', 'NLP doc...'],
175
+ * queries: ['What is ML?', 'What is NLP?'],
176
+ * });
177
+ *
178
+ * console.log(`Saved ${result.data.total_tokens_saved} tokens!`);
179
+ * ```
180
+ */
181
+ async compressBatch(options) {
182
+ const modelName = options.compressionModelName ?? index_js_1.MODELS.LATTE;
183
+ // Batch only supports query-specific models
184
+ if (!index_js_1.QUERY_REQUIRED_MODELS.has(modelName)) {
185
+ throw new index_js_2.ValidationError(`Batch compression only supports query-specific models: ${Array.from(index_js_1.QUERY_REQUIRED_MODELS).join(', ')}`);
186
+ }
187
+ this.validateModel(modelName);
188
+ // Build query list
189
+ const queryList = typeof options.queries === 'string'
190
+ ? Array(options.contexts.length).fill(options.queries)
191
+ : options.queries;
192
+ if (queryList.length !== options.contexts.length) {
193
+ throw new index_js_2.ValidationError(`Number of queries (${queryList.length}) must match number of contexts (${options.contexts.length})`);
194
+ }
195
+ // Build inputs
196
+ const inputs = options.contexts.map((context, i) => ({
197
+ context,
198
+ query: queryList[i],
199
+ }));
200
+ try {
201
+ const request = index_js_3.CompressBatchRequestSchema.parse({
202
+ inputs,
203
+ compression_model_name: modelName,
204
+ target_compression_ratio: options.targetCompressionRatio,
205
+ coarse: options.coarse,
206
+ });
207
+ const response = await this.http.post(index_js_1.ENDPOINTS.COMPRESS_QS_BATCH, request);
208
+ return index_js_3.CompressBatchResponseSchema.parse(response);
209
+ }
210
+ catch (error) {
211
+ if (error instanceof zod_1.ZodError) {
212
+ const firstError = error.errors[0];
213
+ throw new index_js_2.ValidationError(firstError?.message ?? 'Validation failed', firstError?.path.join('.'));
214
+ }
215
+ throw error;
216
+ }
217
+ }
218
+ }
219
+ exports.CompressionClient = CompressionClient;
220
+ //# sourceMappingURL=compression.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compression.js","sourceRoot":"","sources":["../../../src/clients/compression.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export { CompressionClient, type CompressOptions, type CompressBatchOptions, } from './compression.js';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/clients/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC"}
@@ -0,0 +1,6 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CompressionClient = void 0;
4
+ var compression_js_1 = require("./compression.js");
5
+ Object.defineProperty(exports, "CompressionClient", { enumerable: true, get: function () { return compression_js_1.CompressionClient; } });
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/clients/index.ts"],"names":[],"mappings":";;;AAAA,mDAI0B;AAHxB,mHAAA,iBAAiB,OAAA"}