deepbox 0.1.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 (173) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +344 -0
  3. package/dist/CSRMatrix-CwGwQRea.d.cts +219 -0
  4. package/dist/CSRMatrix-KzNt6QpS.d.ts +219 -0
  5. package/dist/Tensor-BQLk1ltW.d.cts +147 -0
  6. package/dist/Tensor-g8mUClel.d.ts +147 -0
  7. package/dist/chunk-4S73VUBD.js +677 -0
  8. package/dist/chunk-4S73VUBD.js.map +1 -0
  9. package/dist/chunk-5R4S63PF.js +2925 -0
  10. package/dist/chunk-5R4S63PF.js.map +1 -0
  11. package/dist/chunk-6AE5FKKQ.cjs +9264 -0
  12. package/dist/chunk-6AE5FKKQ.cjs.map +1 -0
  13. package/dist/chunk-AD436M45.js +3854 -0
  14. package/dist/chunk-AD436M45.js.map +1 -0
  15. package/dist/chunk-ALS7ETWZ.cjs +4263 -0
  16. package/dist/chunk-ALS7ETWZ.cjs.map +1 -0
  17. package/dist/chunk-AU7XHGKJ.js +2092 -0
  18. package/dist/chunk-AU7XHGKJ.js.map +1 -0
  19. package/dist/chunk-B5TNKUEY.js +1481 -0
  20. package/dist/chunk-B5TNKUEY.js.map +1 -0
  21. package/dist/chunk-BCR7G3A6.js +9136 -0
  22. package/dist/chunk-BCR7G3A6.js.map +1 -0
  23. package/dist/chunk-C4PKXY74.cjs +1917 -0
  24. package/dist/chunk-C4PKXY74.cjs.map +1 -0
  25. package/dist/chunk-DWZY6PIP.cjs +6400 -0
  26. package/dist/chunk-DWZY6PIP.cjs.map +1 -0
  27. package/dist/chunk-E3EU5FZO.cjs +2113 -0
  28. package/dist/chunk-E3EU5FZO.cjs.map +1 -0
  29. package/dist/chunk-F3JWBINJ.js +1054 -0
  30. package/dist/chunk-F3JWBINJ.js.map +1 -0
  31. package/dist/chunk-FJYLIGJX.js +1940 -0
  32. package/dist/chunk-FJYLIGJX.js.map +1 -0
  33. package/dist/chunk-JSCDE774.cjs +729 -0
  34. package/dist/chunk-JSCDE774.cjs.map +1 -0
  35. package/dist/chunk-LWECRCW2.cjs +2412 -0
  36. package/dist/chunk-LWECRCW2.cjs.map +1 -0
  37. package/dist/chunk-MLBMYKCG.js +6379 -0
  38. package/dist/chunk-MLBMYKCG.js.map +1 -0
  39. package/dist/chunk-OX6QXFMV.cjs +3874 -0
  40. package/dist/chunk-OX6QXFMV.cjs.map +1 -0
  41. package/dist/chunk-PHV2DKRS.cjs +1072 -0
  42. package/dist/chunk-PHV2DKRS.cjs.map +1 -0
  43. package/dist/chunk-PL7TAYKI.js +4056 -0
  44. package/dist/chunk-PL7TAYKI.js.map +1 -0
  45. package/dist/chunk-PR647I7R.js +1898 -0
  46. package/dist/chunk-PR647I7R.js.map +1 -0
  47. package/dist/chunk-QERHVCHC.cjs +2960 -0
  48. package/dist/chunk-QERHVCHC.cjs.map +1 -0
  49. package/dist/chunk-XEG44RF6.cjs +1514 -0
  50. package/dist/chunk-XEG44RF6.cjs.map +1 -0
  51. package/dist/chunk-XMWVME2W.js +2377 -0
  52. package/dist/chunk-XMWVME2W.js.map +1 -0
  53. package/dist/chunk-ZB75FESB.cjs +1979 -0
  54. package/dist/chunk-ZB75FESB.cjs.map +1 -0
  55. package/dist/chunk-ZLW62TJG.cjs +4061 -0
  56. package/dist/chunk-ZLW62TJG.cjs.map +1 -0
  57. package/dist/chunk-ZXKBDFP3.js +4235 -0
  58. package/dist/chunk-ZXKBDFP3.js.map +1 -0
  59. package/dist/core/index.cjs +204 -0
  60. package/dist/core/index.cjs.map +1 -0
  61. package/dist/core/index.d.cts +2 -0
  62. package/dist/core/index.d.ts +2 -0
  63. package/dist/core/index.js +3 -0
  64. package/dist/core/index.js.map +1 -0
  65. package/dist/dataframe/index.cjs +22 -0
  66. package/dist/dataframe/index.cjs.map +1 -0
  67. package/dist/dataframe/index.d.cts +3 -0
  68. package/dist/dataframe/index.d.ts +3 -0
  69. package/dist/dataframe/index.js +5 -0
  70. package/dist/dataframe/index.js.map +1 -0
  71. package/dist/datasets/index.cjs +134 -0
  72. package/dist/datasets/index.cjs.map +1 -0
  73. package/dist/datasets/index.d.cts +3 -0
  74. package/dist/datasets/index.d.ts +3 -0
  75. package/dist/datasets/index.js +5 -0
  76. package/dist/datasets/index.js.map +1 -0
  77. package/dist/index-74AB8Cyh.d.cts +1126 -0
  78. package/dist/index-9oQx1HgV.d.cts +1180 -0
  79. package/dist/index-BJY2SI4i.d.ts +483 -0
  80. package/dist/index-BWGhrDlr.d.ts +733 -0
  81. package/dist/index-B_DK4FKY.d.cts +242 -0
  82. package/dist/index-BbA2Gxfl.d.ts +456 -0
  83. package/dist/index-BgHYAoSS.d.cts +837 -0
  84. package/dist/index-BndMbqsM.d.ts +1439 -0
  85. package/dist/index-C1mfVYoo.d.ts +2517 -0
  86. package/dist/index-CCvlwAmL.d.cts +809 -0
  87. package/dist/index-CDw5CnOU.d.ts +785 -0
  88. package/dist/index-Cn3SdB0O.d.ts +1126 -0
  89. package/dist/index-CrqLlS-a.d.ts +776 -0
  90. package/dist/index-D61yaSMY.d.cts +483 -0
  91. package/dist/index-D9Loo1_A.d.cts +2517 -0
  92. package/dist/index-DIT_OO9C.d.cts +785 -0
  93. package/dist/index-DIp_RrRt.d.ts +242 -0
  94. package/dist/index-DbultU6X.d.cts +1427 -0
  95. package/dist/index-DmEg_LCm.d.cts +776 -0
  96. package/dist/index-DoPWVxPo.d.cts +1439 -0
  97. package/dist/index-DuCxd-8d.d.ts +837 -0
  98. package/dist/index-Dx42TZaY.d.ts +809 -0
  99. package/dist/index-DyZ4QQf5.d.cts +456 -0
  100. package/dist/index-GFAVyOWO.d.ts +1427 -0
  101. package/dist/index-WHQLn0e8.d.cts +733 -0
  102. package/dist/index-ZtI1Iy4L.d.ts +1180 -0
  103. package/dist/index-eJgeni9c.d.cts +1911 -0
  104. package/dist/index-tk4lSYod.d.ts +1911 -0
  105. package/dist/index.cjs +72 -0
  106. package/dist/index.cjs.map +1 -0
  107. package/dist/index.d.cts +17 -0
  108. package/dist/index.d.ts +17 -0
  109. package/dist/index.js +15 -0
  110. package/dist/index.js.map +1 -0
  111. package/dist/linalg/index.cjs +86 -0
  112. package/dist/linalg/index.cjs.map +1 -0
  113. package/dist/linalg/index.d.cts +3 -0
  114. package/dist/linalg/index.d.ts +3 -0
  115. package/dist/linalg/index.js +5 -0
  116. package/dist/linalg/index.js.map +1 -0
  117. package/dist/metrics/index.cjs +158 -0
  118. package/dist/metrics/index.cjs.map +1 -0
  119. package/dist/metrics/index.d.cts +3 -0
  120. package/dist/metrics/index.d.ts +3 -0
  121. package/dist/metrics/index.js +5 -0
  122. package/dist/metrics/index.js.map +1 -0
  123. package/dist/ml/index.cjs +87 -0
  124. package/dist/ml/index.cjs.map +1 -0
  125. package/dist/ml/index.d.cts +3 -0
  126. package/dist/ml/index.d.ts +3 -0
  127. package/dist/ml/index.js +6 -0
  128. package/dist/ml/index.js.map +1 -0
  129. package/dist/ndarray/index.cjs +501 -0
  130. package/dist/ndarray/index.cjs.map +1 -0
  131. package/dist/ndarray/index.d.cts +5 -0
  132. package/dist/ndarray/index.d.ts +5 -0
  133. package/dist/ndarray/index.js +4 -0
  134. package/dist/ndarray/index.js.map +1 -0
  135. package/dist/nn/index.cjs +142 -0
  136. package/dist/nn/index.cjs.map +1 -0
  137. package/dist/nn/index.d.cts +6 -0
  138. package/dist/nn/index.d.ts +6 -0
  139. package/dist/nn/index.js +5 -0
  140. package/dist/nn/index.js.map +1 -0
  141. package/dist/optim/index.cjs +77 -0
  142. package/dist/optim/index.cjs.map +1 -0
  143. package/dist/optim/index.d.cts +4 -0
  144. package/dist/optim/index.d.ts +4 -0
  145. package/dist/optim/index.js +4 -0
  146. package/dist/optim/index.js.map +1 -0
  147. package/dist/plot/index.cjs +114 -0
  148. package/dist/plot/index.cjs.map +1 -0
  149. package/dist/plot/index.d.cts +6 -0
  150. package/dist/plot/index.d.ts +6 -0
  151. package/dist/plot/index.js +5 -0
  152. package/dist/plot/index.js.map +1 -0
  153. package/dist/preprocess/index.cjs +82 -0
  154. package/dist/preprocess/index.cjs.map +1 -0
  155. package/dist/preprocess/index.d.cts +4 -0
  156. package/dist/preprocess/index.d.ts +4 -0
  157. package/dist/preprocess/index.js +5 -0
  158. package/dist/preprocess/index.js.map +1 -0
  159. package/dist/random/index.cjs +74 -0
  160. package/dist/random/index.cjs.map +1 -0
  161. package/dist/random/index.d.cts +3 -0
  162. package/dist/random/index.d.ts +3 -0
  163. package/dist/random/index.js +5 -0
  164. package/dist/random/index.js.map +1 -0
  165. package/dist/stats/index.cjs +142 -0
  166. package/dist/stats/index.cjs.map +1 -0
  167. package/dist/stats/index.d.cts +3 -0
  168. package/dist/stats/index.d.ts +3 -0
  169. package/dist/stats/index.js +5 -0
  170. package/dist/stats/index.js.map +1 -0
  171. package/dist/tensor-B96jjJLQ.d.cts +205 -0
  172. package/dist/tensor-B96jjJLQ.d.ts +205 -0
  173. package/package.json +226 -0
@@ -0,0 +1,785 @@
1
+ import { D as DType, a as Device, S as Shape, A as Axis, b as TypedArray, c as DEVICES, d as DTYPES, T as TensorLike, e as TensorStorage, i as isDType, f as isDevice } from './tensor-B96jjJLQ.cjs';
2
+
3
+ /**
4
+ * Global configuration for Deepbox.
5
+ *
6
+ * @property defaultDtype - Default data type for new tensors
7
+ * @property defaultDevice - Default compute device
8
+ * @property seed - Random seed for reproducibility (null = not set)
9
+ */
10
+ type DeepboxConfig = {
11
+ readonly defaultDtype: DType;
12
+ readonly defaultDevice: Device;
13
+ readonly seed: number | null;
14
+ };
15
+ /**
16
+ * Get the current global configuration.
17
+ *
18
+ * Returns a copy of the configuration to prevent external mutation.
19
+ *
20
+ * @returns Current configuration object
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * import { getConfig } from 'deepbox/core';
25
+ *
26
+ * const config = getConfig();
27
+ * console.log(config.defaultDtype); // 'float32'
28
+ * ```
29
+ */
30
+ declare function getConfig(): Readonly<DeepboxConfig>;
31
+ /**
32
+ * Update global configuration.
33
+ *
34
+ * Merges provided settings with current configuration.
35
+ * Only specified fields are updated.
36
+ *
37
+ * @param next - Partial configuration to merge
38
+ * @throws {DataValidationError} If config is invalid or contains unknown keys
39
+ *
40
+ * @example
41
+ * ```ts
42
+ * import { setConfig } from 'deepbox/core';
43
+ *
44
+ * setConfig({
45
+ * defaultDtype: 'float64',
46
+ * seed: 42
47
+ * });
48
+ * ```
49
+ */
50
+ declare function setConfig(next: Partial<DeepboxConfig>): void;
51
+ /**
52
+ * Reset configuration to default values.
53
+ *
54
+ * @example
55
+ * ```ts
56
+ * import { resetConfig } from 'deepbox/core';
57
+ *
58
+ * resetConfig(); // Back to defaults
59
+ * ```
60
+ */
61
+ declare function resetConfig(): void;
62
+ /**
63
+ * Set the global random seed for reproducibility.
64
+ *
65
+ * @param seed - Integer seed value
66
+ * @throws {DataValidationError} If seed is not a safe integer
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * import { setSeed } from 'deepbox/core';
71
+ *
72
+ * setSeed(42); // All random operations now reproducible
73
+ * ```
74
+ */
75
+ declare function setSeed(seed: number): void;
76
+ /**
77
+ * Get the current random seed.
78
+ *
79
+ * @returns Current seed value or null if not set
80
+ */
81
+ declare function getSeed(): number | null;
82
+ /**
83
+ * Set the default compute device.
84
+ *
85
+ * @param device - Device to use ('cpu', 'webgpu', or 'wasm')
86
+ * @throws {DataValidationError} If device is not supported
87
+ *
88
+ * @example
89
+ * ```ts
90
+ * import { setDevice } from 'deepbox/core';
91
+ *
92
+ * setDevice('cpu'); // Use CPU for all operations
93
+ * ```
94
+ */
95
+ declare function setDevice(device: Device): void;
96
+ /**
97
+ * Get the current default device.
98
+ *
99
+ * @returns Current default device
100
+ */
101
+ declare function getDevice(): Device;
102
+ /**
103
+ * Set the default data type for new tensors.
104
+ *
105
+ * @param dtype - Data type to use as default
106
+ * @throws {DataValidationError} If dtype is not supported
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * import { setDtype } from 'deepbox/core';
111
+ *
112
+ * setDtype('float64'); // Use double precision by default
113
+ * ```
114
+ */
115
+ declare function setDtype(dtype: DType): void;
116
+ /**
117
+ * Get the current default data type.
118
+ *
119
+ * @returns Current default dtype
120
+ */
121
+ declare function getDtype(): DType;
122
+
123
+ /**
124
+ * Base class for all Deepbox-specific errors.
125
+ *
126
+ * Provides a stable `instanceof DeepboxError` discriminator
127
+ * and consistent `cause` chaining.
128
+ */
129
+ declare class DeepboxError extends Error {
130
+ name: string;
131
+ cause?: unknown;
132
+ constructor(message?: string, options?: {
133
+ readonly cause?: unknown;
134
+ });
135
+ }
136
+
137
+ /**
138
+ * Error thrown when tensor shapes cannot be broadcast together.
139
+ *
140
+ * Broadcasting allows operations on tensors of different shapes by automatically
141
+ * expanding dimensions. This error occurs when shapes are incompatible.
142
+ *
143
+ * @example
144
+ * ```ts
145
+ * // Broadcasting (3, 4) and (4,) works -> (3, 4)
146
+ * // Broadcasting (3, 4) and (3,) fails
147
+ * if (!canBroadcast(shape1, shape2)) {
148
+ * throw new BroadcastError(shape1, shape2);
149
+ * }
150
+ * ```
151
+ *
152
+ * References:
153
+ * - NumPy broadcasting: https://numpy.org/doc/stable/user/basics.broadcasting.html
154
+ */
155
+ declare class BroadcastError extends DeepboxError {
156
+ name: string;
157
+ /** The first shape involved in the broadcast operation */
158
+ readonly shape1: Shape;
159
+ /** The second shape involved in the broadcast operation */
160
+ readonly shape2: Shape;
161
+ constructor(shape1: Shape, shape2: Shape, context?: string);
162
+ }
163
+
164
+ /**
165
+ * Details for convergence failures.
166
+ *
167
+ * @property iterations - Number of iterations completed before failure
168
+ * @property tolerance - Tolerance value used for convergence checks
169
+ */
170
+ type ConvergenceErrorDetails = {
171
+ readonly iterations?: number;
172
+ readonly tolerance?: number;
173
+ };
174
+ /**
175
+ * Error thrown when an iterative algorithm fails to converge within
176
+ * the maximum allowed iterations.
177
+ *
178
+ * This is a thrown exception that extends {@link DeepboxError}; callers
179
+ * should handle it with standard try/catch.
180
+ *
181
+ * @example
182
+ * ```ts
183
+ * if (iterations >= maxIterations) {
184
+ * throw new ConvergenceError(
185
+ * `Algorithm did not converge after ${maxIterations} iterations`
186
+ * );
187
+ * }
188
+ * ```
189
+ *
190
+ * References:
191
+ * - scikit-learn convergence diagnostics:
192
+ * https://scikit-learn.org/stable/modules/generated/sklearn.exceptions.ConvergenceWarning.html
193
+ */
194
+ declare class ConvergenceError extends DeepboxError {
195
+ name: string;
196
+ /** Number of iterations completed before convergence failure */
197
+ readonly iterations?: number;
198
+ /** Tolerance value used for convergence check */
199
+ readonly tolerance?: number;
200
+ constructor(message: string, details?: ConvergenceErrorDetails);
201
+ }
202
+
203
+ /**
204
+ * Error thrown when an operation is requested on an unsupported or unavailable compute device.
205
+ *
206
+ * This is intended for device selection / dispatch layers (e.g. attempting to use `webgpu`
207
+ * in an environment where WebGPU is not available).
208
+ */
209
+ declare class DeviceError extends DeepboxError {
210
+ /**
211
+ * Discriminator name for this error type.
212
+ */
213
+ name: string;
214
+ }
215
+
216
+ /**
217
+ * Error thrown when a requested dtype is unsupported or cannot be handled by the current
218
+ * implementation.
219
+ *
220
+ * This is used in low-level dtype utilities (e.g. mapping a `DType` to a TypedArray
221
+ * constructor) to provide a stable, package-specific error type.
222
+ */
223
+ declare class DTypeError extends DeepboxError {
224
+ /**
225
+ * Discriminator name for this error type.
226
+ */
227
+ name: string;
228
+ }
229
+
230
+ /**
231
+ * Error thrown when an invalid index is used to access tensor elements.
232
+ *
233
+ * @example
234
+ * ```ts
235
+ * if (index < 0 || index >= length) {
236
+ * throw new IndexError(`Index ${index} is out of bounds for length ${length}`);
237
+ * }
238
+ * ```
239
+ */
240
+ declare class IndexError extends DeepboxError {
241
+ name: string;
242
+ /** The invalid index value */
243
+ readonly index?: number;
244
+ /** The valid range for the index */
245
+ readonly validRange?: readonly [number, number];
246
+ constructor(message: string, details?: {
247
+ readonly index?: number;
248
+ readonly validRange?: readonly [number, number];
249
+ });
250
+ }
251
+
252
+ /**
253
+ * Error thrown when invalid parameters are passed to a function or method.
254
+ *
255
+ * @example
256
+ * ```ts
257
+ * function kmeans(k: number, maxIter: number) {
258
+ * if (k <= 0) {
259
+ * throw new InvalidParameterError('k must be positive', 'k', k);
260
+ * }
261
+ * // ... algorithm logic
262
+ * }
263
+ * ```
264
+ */
265
+ declare class InvalidParameterError extends DeepboxError {
266
+ name: string;
267
+ /** The name of the invalid parameter */
268
+ readonly parameterName?: string;
269
+ /** The invalid value that was provided */
270
+ readonly value?: unknown;
271
+ constructor(message: string, parameterName?: string, value?: unknown);
272
+ }
273
+
274
+ /**
275
+ * Error thrown when memory allocation fails or memory limits are exceeded.
276
+ *
277
+ * @example
278
+ * ```ts
279
+ * if (requestedBytes > MAX_MEMORY) {
280
+ * throw new MemoryError(`Cannot allocate ${requestedBytes} bytes`);
281
+ * }
282
+ * ```
283
+ */
284
+ declare class MemoryError extends DeepboxError {
285
+ name: string;
286
+ /** The amount of memory requested in bytes */
287
+ readonly requestedBytes?: number;
288
+ /** The amount of memory available in bytes */
289
+ readonly availableBytes?: number;
290
+ constructor(message: string, details?: {
291
+ readonly requestedBytes?: number;
292
+ readonly availableBytes?: number;
293
+ });
294
+ }
295
+
296
+ /**
297
+ * Error thrown when a model or estimator is used before being fitted.
298
+ *
299
+ * This is analogous to sklearn's NotFittedError.
300
+ *
301
+ * @example
302
+ * ```ts
303
+ * class MyModel {
304
+ * private fitted = false;
305
+ *
306
+ * fit(X: Tensor, y: Tensor) {
307
+ * // ... fitting logic
308
+ * this.fitted = true;
309
+ * }
310
+ *
311
+ * predict(X: Tensor) {
312
+ * if (!this.fitted) {
313
+ * throw new NotFittedError('Model must be fitted before prediction');
314
+ * }
315
+ * // ... prediction logic
316
+ * }
317
+ * }
318
+ * ```
319
+ *
320
+ * References:
321
+ * - scikit-learn NotFittedError: https://scikit-learn.org/stable/modules/generated/sklearn.exceptions.NotFittedError.html
322
+ */
323
+ declare class NotFittedError extends DeepboxError {
324
+ name: string;
325
+ /** The name of the model or estimator that was not fitted */
326
+ readonly modelName?: string;
327
+ constructor(message: string, modelName?: string);
328
+ }
329
+
330
+ /**
331
+ * Error thrown when a method or code path exists in the public API but is not implemented yet.
332
+ *
333
+ * Use this instead of a generic `Error` so callers can reliably detect this specific
334
+ * capability gap.
335
+ */
336
+ declare class NotImplementedError extends DeepboxError {
337
+ /**
338
+ * Discriminator name for this error type.
339
+ */
340
+ name: string;
341
+ /**
342
+ * Create a new NotImplementedError.
343
+ *
344
+ * @param message - Optional error message.
345
+ */
346
+ constructor(message?: string);
347
+ }
348
+
349
+ /**
350
+ * Details about a shape mismatch error.
351
+ *
352
+ * @property expected - The expected shape
353
+ * @property received - The actual shape that was received
354
+ * @property context - Additional context about where the error occurred
355
+ */
356
+ type ShapeErrorDetails = {
357
+ readonly expected?: Shape;
358
+ readonly received?: Shape;
359
+ readonly context?: string;
360
+ };
361
+ /**
362
+ * Error thrown when tensor shapes are incompatible or invalid.
363
+ *
364
+ * This error is used throughout the library when operations require specific
365
+ * tensor shapes that don't match the provided tensors.
366
+ *
367
+ * @example
368
+ * ```ts
369
+ * import { ShapeError } from 'deepbox/core';
370
+ *
371
+ * if (tensor.shape[0] !== expectedRows) {
372
+ * throw ShapeError.mismatch([expectedRows, cols], tensor.shape, 'matrix multiplication');
373
+ * }
374
+ * ```
375
+ */
376
+ declare class ShapeError extends DeepboxError {
377
+ name: string;
378
+ readonly expected: Shape | undefined;
379
+ readonly received: Shape | undefined;
380
+ readonly context: string | undefined;
381
+ constructor(message: string, details?: ShapeErrorDetails);
382
+ /**
383
+ * Create a ShapeError for a shape mismatch.
384
+ *
385
+ * Convenience factory method for the common case of shape mismatches.
386
+ *
387
+ * @param expected - The expected shape
388
+ * @param received - The actual shape that was received
389
+ * @param context - Optional context about where the mismatch occurred
390
+ * @returns A new ShapeError with formatted message and details
391
+ *
392
+ * @example
393
+ * ```ts
394
+ * throw ShapeError.mismatch([3, 4], [3, 5], 'matrix multiplication');
395
+ * // Error: Shape mismatch (matrix multiplication): expected [3,4], received [3,5]
396
+ * ```
397
+ */
398
+ static mismatch(expected: Shape, received: Shape, context?: string): ShapeError;
399
+ }
400
+
401
+ /**
402
+ * Error thrown when data validation fails.
403
+ *
404
+ * Used for input data that doesn't meet expected format or constraints.
405
+ *
406
+ * @example
407
+ * ```ts
408
+ * if (!Array.isArray(data)) {
409
+ * throw new DataValidationError('Expected array input');
410
+ * }
411
+ * ```
412
+ */
413
+ declare class DataValidationError extends DeepboxError {
414
+ name: string;
415
+ }
416
+
417
+ /**
418
+ * Normalize an axis argument to a valid dimension index.
419
+ *
420
+ * Supports negative indexing (Python-style) and string aliases:
421
+ * - "index" or "rows" -> 0
422
+ * - "columns" -> 1
423
+ *
424
+ * @param axis - Axis identifier (index or alias)
425
+ * @param ndim - Number of dimensions in the tensor
426
+ * @returns Non-negative integer dimension index
427
+ * @throws {InvalidParameterError} If axis is out of bounds
428
+ * @throws {InvalidParameterError} If axis alias is invalid
429
+ */
430
+ declare function normalizeAxis(axis: Axis, ndim: number): number;
431
+ /**
432
+ * Normalize a list of axes to valid dimension indices.
433
+ *
434
+ * Checks for duplicates and validity of each axis.
435
+ *
436
+ * @param axis - Single axis or array of axes
437
+ * @param ndim - Number of dimensions
438
+ * @returns Array of unique non-negative integer dimension indices
439
+ * @throws {InvalidParameterError} If any axis is invalid, out of bounds, or duplicated
440
+ */
441
+ declare function normalizeAxes(axis: Axis | Axis[], ndim: number): number[];
442
+
443
+ type NumericDType = Exclude<DType, "string">;
444
+ /**
445
+ * Ensure a dtype is numeric (non-string).
446
+ *
447
+ * @param dtype - Data type identifier
448
+ * @param context - Context string for error messages
449
+ * @returns The same dtype narrowed to numeric types
450
+ * @throws {DTypeError} If dtype is 'string'
451
+ */
452
+ declare function ensureNumericDType(dtype: DType, context: string): NumericDType;
453
+ /**
454
+ * Get TypedArray constructor for a given DType.
455
+ *
456
+ * Maps Deepbox dtype strings to JavaScript TypedArray constructors.
457
+ * Used internally for allocating tensor storage.
458
+ *
459
+ * **Mapping:**
460
+ * - `float32` → `Float32Array`
461
+ * - `float64` → `Float64Array`
462
+ * - `int32` → `Int32Array`
463
+ * - `int64` → `BigInt64Array`
464
+ * - `uint8` → `Uint8Array`
465
+ * - `bool` → `Uint8Array` (1 byte per boolean)
466
+ * - `string` → Not supported (throws error)
467
+ *
468
+ * @param dtype - Data type identifier
469
+ * @returns TypedArray constructor for the given dtype
470
+ * @throws {DTypeError} If dtype is 'string' (not yet supported)
471
+ *
472
+ * @example
473
+ * ```ts
474
+ * const Ctor = dtypeToTypedArrayCtor('float32');
475
+ * const arr = new Ctor(10); // Float32Array with 10 elements
476
+ * ```
477
+ */
478
+ declare function dtypeToTypedArrayCtor(dtype: DType): Float32ArrayConstructor | Float64ArrayConstructor | Int32ArrayConstructor | BigInt64ArrayConstructor | Uint8ArrayConstructor;
479
+
480
+ /**
481
+ * Type-safe typed array accessor utilities.
482
+ *
483
+ * These utilities provide safe access to TypedArray elements without
484
+ * requiring unsafe type assertions. They handle the `noUncheckedIndexedAccess`
485
+ * TypeScript configuration properly.
486
+ *
487
+ * Element accessors for TypedArray storage throw {@link IndexError} on
488
+ * out-of-bounds access to surface stride/index bugs immediately rather
489
+ * than silently returning zero.
490
+ */
491
+
492
+ /**
493
+ * Numeric typed arrays (excludes BigInt64Array).
494
+ */
495
+ type NumericTypedArray = Float32Array | Float64Array | Int32Array | Uint8Array;
496
+ /**
497
+ * Get an element from a numeric typed array at the specified index.
498
+ *
499
+ * @param arr - The numeric typed array
500
+ * @param index - The index to access
501
+ * @returns The element at the index
502
+ * @throws {IndexError} If the index is out of bounds
503
+ */
504
+ declare function getNumericElement(arr: NumericTypedArray, index: number): number;
505
+ /**
506
+ * Get an element from a BigInt64Array at the specified index.
507
+ *
508
+ * @param arr - The BigInt64Array
509
+ * @param index - The index to access
510
+ * @returns The element at the index
511
+ * @throws {IndexError} If the index is out of bounds
512
+ */
513
+ declare function getBigIntElement(arr: BigInt64Array, index: number): bigint;
514
+ /**
515
+ * Get an element from a TypedArray, returning as number.
516
+ * For BigInt64Array, converts to number (throws if out of safe integer range).
517
+ *
518
+ * @param arr - The typed array
519
+ * @param index - The index to access
520
+ * @returns The element at the index as a number
521
+ * @throws {IndexError} If the index is out of bounds
522
+ * @throws {DataValidationError} If a bigint value exceeds the safe integer range
523
+ */
524
+ declare function getElementAsNumber(arr: TypedArray, index: number): number;
525
+ /**
526
+ * Get an element from a shape array at the specified index.
527
+ * Returns 1 if the index is out of bounds (used in broadcasting where
528
+ * missing leading dimensions are treated as size 1).
529
+ *
530
+ * @param shape - The shape array
531
+ * @param index - The index to access
532
+ * @returns The dimension at the index, or 1 if out of bounds
533
+ */
534
+ declare function getShapeDim(shape: readonly number[], index: number): number;
535
+ /**
536
+ * Get an element from a number array at the specified index.
537
+ * Returns the provided default value if the index is out of bounds.
538
+ *
539
+ * @param arr - The number array
540
+ * @param index - The index to access
541
+ * @param defaultValue - The default value to return if out of bounds (default: 0)
542
+ * @returns The element at the index, or the default value if out of bounds
543
+ */
544
+ declare function getArrayElement(arr: readonly number[], index: number, defaultValue?: number): number;
545
+ /**
546
+ * Safely get a string from a string array at the specified index.
547
+ * Returns empty string if the index is out of bounds.
548
+ *
549
+ * @param arr - The string array
550
+ * @param index - The index to access
551
+ * @returns The string at the index, or empty string if out of bounds
552
+ */
553
+ declare function getStringElement(arr: readonly string[], index: number): string;
554
+ /**
555
+ * Create a readonly number array from mutable array with proper typing.
556
+ * This avoids the need for `as Shape` assertions.
557
+ *
558
+ * @param arr - The mutable number array
559
+ * @returns The same array typed as readonly
560
+ */
561
+ declare function asReadonlyArray<T extends number[]>(arr: T): readonly number[];
562
+ /**
563
+ * Type guard to check if a typed array is a BigInt64Array.
564
+ *
565
+ * @param arr - The typed array to check
566
+ * @returns True if the array is a BigInt64Array
567
+ */
568
+ declare function isBigInt64Array(arr: TypedArray): arr is BigInt64Array;
569
+ /**
570
+ * Type guard to check if a typed array is a numeric (non-BigInt) array.
571
+ *
572
+ * @param arr - The typed array to check
573
+ * @returns True if the array is a numeric typed array
574
+ */
575
+ declare function isNumericTypedArray(arr: TypedArray): arr is NumericTypedArray;
576
+
577
+ /**
578
+ * Type guard to check if a value is one of the supported TypedArray types.
579
+ *
580
+ * Returns true only for the exact TypedArray subclasses in the Deepbox
581
+ * {@link TypedArray} union: Float32Array, Float64Array, Int32Array,
582
+ * BigInt64Array, and Uint8Array. Returns false for unsupported typed arrays
583
+ * (e.g. Uint16Array, Int16Array), DataView, and regular arrays.
584
+ *
585
+ * @param value - The value to check
586
+ * @returns True if value is a supported TypedArray, false otherwise
587
+ *
588
+ * @example
589
+ * ```ts
590
+ * import { isTypedArray } from 'deepbox/core';
591
+ *
592
+ * isTypedArray(new Float32Array(10)); // true
593
+ * isTypedArray(new Uint16Array(10)); // false (unsupported)
594
+ * isTypedArray([1, 2, 3]); // false
595
+ * isTypedArray(new DataView(new ArrayBuffer(10))); // false
596
+ * ```
597
+ */
598
+ declare function isTypedArray(value: unknown): value is TypedArray;
599
+
600
+ /**
601
+ * Calculate the total number of elements from a shape.
602
+ *
603
+ * @param shape - The shape to calculate size from
604
+ * @param name - Parameter name for error messages (default: 'shape')
605
+ * @returns Total number of elements
606
+ * @throws {DataValidationError} If shape is invalid or size exceeds safe integer range
607
+ */
608
+ declare function shapeToSize(shape: Shape): number;
609
+ declare function shapeToSize(shape: unknown, name?: string): number;
610
+ /**
611
+ * Validate that a shape is well-formed.
612
+ *
613
+ * Checks that:
614
+ * - Value is an array
615
+ * - All elements are finite non-negative integers
616
+ * - All elements are safe integers
617
+ *
618
+ * @param shape - The shape to validate
619
+ * @param name - Parameter name for error messages (default: 'shape')
620
+ * @returns The validated shape
621
+ * @throws {DataValidationError} If shape is invalid
622
+ */
623
+ declare function validateShape(shape: Shape, name?: string): Shape;
624
+ declare function validateShape(shape: unknown, name?: string): Shape;
625
+ /**
626
+ * Validate that a `dtype` is supported.
627
+ *
628
+ * @param dtype - The data type to validate
629
+ * @param name - The parameter name for error messages
630
+ * @returns The validated dtype (typed as {@link DType})
631
+ * @throws {DataValidationError} If dtype is not valid
632
+ */
633
+ declare function validateDtype(dtype: DType, name?: string): DType;
634
+ declare function validateDtype(dtype: unknown, name?: string): DType;
635
+ /**
636
+ * Validate that a `device` is supported.
637
+ *
638
+ * @param device - The device to validate
639
+ * @param name - The parameter name for error messages
640
+ * @returns The validated device (typed as {@link Device})
641
+ * @throws {DataValidationError} If device is not valid
642
+ */
643
+ declare function validateDevice(device: Device, name?: string): Device;
644
+ declare function validateDevice(device: unknown, name?: string): Device;
645
+ /**
646
+ * Validate that a value is positive (> 0).
647
+ *
648
+ * @param value - The value to validate
649
+ * @param name - The parameter name for error messages
650
+ * @throws {DataValidationError} If value is not positive
651
+ */
652
+ declare function validatePositive(value: number, name: string): void;
653
+ /**
654
+ * Validate that a value is non-negative (>= 0).
655
+ *
656
+ * @param value - The value to validate
657
+ * @param name - The parameter name for error messages
658
+ * @throws {DataValidationError} If value is negative
659
+ */
660
+ declare function validateNonNegative(value: number, name: string): void;
661
+ /**
662
+ * Validate that a value is within a specified range [min, max].
663
+ *
664
+ * @param value - The value to validate
665
+ * @param min - The minimum allowed value (inclusive)
666
+ * @param max - The maximum allowed value (inclusive)
667
+ * @param name - The parameter name for error messages
668
+ * @throws {DataValidationError} If value is out of range or bounds are invalid
669
+ */
670
+ declare function validateRange(value: number, min: number, max: number, name: string): void;
671
+ /**
672
+ * Validate that a value is a safe integer.
673
+ *
674
+ * @param value - The value to validate
675
+ * @param name - The parameter name for error messages
676
+ * @throws {DataValidationError} If value is not a safe integer
677
+ */
678
+ declare function validateInteger(value: number, name: string): void;
679
+ /**
680
+ * Validate that a value is one of the allowed options.
681
+ *
682
+ * @param value - The value to validate
683
+ * @param options - The array of allowed values
684
+ * @param name - The parameter name for error messages
685
+ * @throws {DataValidationError} If value is not in options
686
+ */
687
+ declare function validateOneOf<T extends string>(value: unknown, options: readonly T[], name: string): asserts value is T;
688
+ /**
689
+ * Validate that a value is an array.
690
+ *
691
+ * @param arr - The value to validate
692
+ * @param name - The parameter name for error messages
693
+ * @throws {DataValidationError} If value is not an array
694
+ */
695
+ declare function validateArray(arr: unknown, name: string): asserts arr is unknown[];
696
+
697
+ /**
698
+ * Deepbox Core
699
+ *
700
+ * This module is the stable, dependency-light foundation shared by all other Deepbox
701
+ * subpackages. It exposes:
702
+ * - configuration helpers
703
+ * - error types
704
+ * - foundational types/constants
705
+ * - runtime validation and utility helpers
706
+ */
707
+
708
+ declare const index_Axis: typeof Axis;
709
+ type index_BroadcastError = BroadcastError;
710
+ declare const index_BroadcastError: typeof BroadcastError;
711
+ type index_ConvergenceError = ConvergenceError;
712
+ declare const index_ConvergenceError: typeof ConvergenceError;
713
+ type index_ConvergenceErrorDetails = ConvergenceErrorDetails;
714
+ declare const index_DEVICES: typeof DEVICES;
715
+ declare const index_DTYPES: typeof DTYPES;
716
+ declare const index_DType: typeof DType;
717
+ type index_DTypeError = DTypeError;
718
+ declare const index_DTypeError: typeof DTypeError;
719
+ type index_DataValidationError = DataValidationError;
720
+ declare const index_DataValidationError: typeof DataValidationError;
721
+ type index_DeepboxConfig = DeepboxConfig;
722
+ type index_DeepboxError = DeepboxError;
723
+ declare const index_DeepboxError: typeof DeepboxError;
724
+ declare const index_Device: typeof Device;
725
+ type index_DeviceError = DeviceError;
726
+ declare const index_DeviceError: typeof DeviceError;
727
+ type index_IndexError = IndexError;
728
+ declare const index_IndexError: typeof IndexError;
729
+ type index_InvalidParameterError = InvalidParameterError;
730
+ declare const index_InvalidParameterError: typeof InvalidParameterError;
731
+ type index_MemoryError = MemoryError;
732
+ declare const index_MemoryError: typeof MemoryError;
733
+ type index_NotFittedError = NotFittedError;
734
+ declare const index_NotFittedError: typeof NotFittedError;
735
+ type index_NotImplementedError = NotImplementedError;
736
+ declare const index_NotImplementedError: typeof NotImplementedError;
737
+ type index_NumericDType = NumericDType;
738
+ type index_NumericTypedArray = NumericTypedArray;
739
+ declare const index_Shape: typeof Shape;
740
+ type index_ShapeError = ShapeError;
741
+ declare const index_ShapeError: typeof ShapeError;
742
+ type index_ShapeErrorDetails = ShapeErrorDetails;
743
+ declare const index_TensorLike: typeof TensorLike;
744
+ declare const index_TensorStorage: typeof TensorStorage;
745
+ declare const index_TypedArray: typeof TypedArray;
746
+ declare const index_asReadonlyArray: typeof asReadonlyArray;
747
+ declare const index_dtypeToTypedArrayCtor: typeof dtypeToTypedArrayCtor;
748
+ declare const index_ensureNumericDType: typeof ensureNumericDType;
749
+ declare const index_getArrayElement: typeof getArrayElement;
750
+ declare const index_getBigIntElement: typeof getBigIntElement;
751
+ declare const index_getConfig: typeof getConfig;
752
+ declare const index_getDevice: typeof getDevice;
753
+ declare const index_getDtype: typeof getDtype;
754
+ declare const index_getElementAsNumber: typeof getElementAsNumber;
755
+ declare const index_getNumericElement: typeof getNumericElement;
756
+ declare const index_getSeed: typeof getSeed;
757
+ declare const index_getShapeDim: typeof getShapeDim;
758
+ declare const index_getStringElement: typeof getStringElement;
759
+ declare const index_isBigInt64Array: typeof isBigInt64Array;
760
+ declare const index_isDType: typeof isDType;
761
+ declare const index_isDevice: typeof isDevice;
762
+ declare const index_isNumericTypedArray: typeof isNumericTypedArray;
763
+ declare const index_isTypedArray: typeof isTypedArray;
764
+ declare const index_normalizeAxes: typeof normalizeAxes;
765
+ declare const index_normalizeAxis: typeof normalizeAxis;
766
+ declare const index_resetConfig: typeof resetConfig;
767
+ declare const index_setConfig: typeof setConfig;
768
+ declare const index_setDevice: typeof setDevice;
769
+ declare const index_setDtype: typeof setDtype;
770
+ declare const index_setSeed: typeof setSeed;
771
+ declare const index_shapeToSize: typeof shapeToSize;
772
+ declare const index_validateArray: typeof validateArray;
773
+ declare const index_validateDevice: typeof validateDevice;
774
+ declare const index_validateDtype: typeof validateDtype;
775
+ declare const index_validateInteger: typeof validateInteger;
776
+ declare const index_validateNonNegative: typeof validateNonNegative;
777
+ declare const index_validateOneOf: typeof validateOneOf;
778
+ declare const index_validatePositive: typeof validatePositive;
779
+ declare const index_validateRange: typeof validateRange;
780
+ declare const index_validateShape: typeof validateShape;
781
+ declare namespace index {
782
+ export { index_Axis as Axis, index_BroadcastError as BroadcastError, index_ConvergenceError as ConvergenceError, type index_ConvergenceErrorDetails as ConvergenceErrorDetails, index_DEVICES as DEVICES, index_DTYPES as DTYPES, index_DType as DType, index_DTypeError as DTypeError, index_DataValidationError as DataValidationError, type index_DeepboxConfig as DeepboxConfig, index_DeepboxError as DeepboxError, index_Device as Device, index_DeviceError as DeviceError, index_IndexError as IndexError, index_InvalidParameterError as InvalidParameterError, index_MemoryError as MemoryError, index_NotFittedError as NotFittedError, index_NotImplementedError as NotImplementedError, type index_NumericDType as NumericDType, type index_NumericTypedArray as NumericTypedArray, index_Shape as Shape, index_ShapeError as ShapeError, type index_ShapeErrorDetails as ShapeErrorDetails, index_TensorLike as TensorLike, index_TensorStorage as TensorStorage, index_TypedArray as TypedArray, index_asReadonlyArray as asReadonlyArray, index_dtypeToTypedArrayCtor as dtypeToTypedArrayCtor, index_ensureNumericDType as ensureNumericDType, index_getArrayElement as getArrayElement, index_getBigIntElement as getBigIntElement, index_getConfig as getConfig, index_getDevice as getDevice, index_getDtype as getDtype, index_getElementAsNumber as getElementAsNumber, index_getNumericElement as getNumericElement, index_getSeed as getSeed, index_getShapeDim as getShapeDim, index_getStringElement as getStringElement, index_isBigInt64Array as isBigInt64Array, index_isDType as isDType, index_isDevice as isDevice, index_isNumericTypedArray as isNumericTypedArray, index_isTypedArray as isTypedArray, index_normalizeAxes as normalizeAxes, index_normalizeAxis as normalizeAxis, index_resetConfig as resetConfig, index_setConfig as setConfig, index_setDevice as setDevice, index_setDtype as setDtype, index_setSeed as setSeed, index_shapeToSize as shapeToSize, index_validateArray as validateArray, index_validateDevice as validateDevice, index_validateDtype as validateDtype, index_validateInteger as validateInteger, index_validateNonNegative as validateNonNegative, index_validateOneOf as validateOneOf, index_validatePositive as validatePositive, index_validateRange as validateRange, index_validateShape as validateShape };
783
+ }
784
+
785
+ export { getStringElement as A, BroadcastError as B, ConvergenceError as C, type DeepboxConfig as D, isBigInt64Array as E, isNumericTypedArray as F, isTypedArray as G, type NumericDType as H, IndexError as I, type NumericTypedArray as J, normalizeAxes as K, normalizeAxis as L, MemoryError as M, NotFittedError as N, shapeToSize as O, validateArray as P, validateDevice as Q, validateDtype as R, ShapeError as S, validateInteger as T, validateNonNegative as U, validateOneOf as V, validatePositive as W, validateRange as X, validateShape as Y, getDevice as a, getDtype as b, getSeed as c, setDevice as d, setDtype as e, setSeed as f, getConfig as g, type ConvergenceErrorDetails as h, index as i, DataValidationError as j, DeepboxError as k, DeviceError as l, DTypeError as m, InvalidParameterError as n, NotImplementedError as o, type ShapeErrorDetails as p, asReadonlyArray as q, resetConfig as r, setConfig as s, dtypeToTypedArrayCtor as t, ensureNumericDType as u, getArrayElement as v, getBigIntElement as w, getElementAsNumber as x, getNumericElement as y, getShapeDim as z };