deepbox 0.1.0

package/dist/index-B_DK4FKY.d.cts

@@ -0,0 +1,242 @@
+import { A as Axis, D as DType, S as Shape, b as TypedArray } from './tensor-B96jjJLQ.cjs';
+import { T as Tensor } from './Tensor-BQLk1ltW.cjs';
+
+type SliceRange = number | {
+    readonly start?: number;
+    readonly end?: number;
+    readonly step?: number;
+};
+/**
+ * Slice a tensor.
+ *
+ * Examples:
+ * - `slice(t, { start: 0, end: 2 })` on a 1D tensor keeps the first 2 elements.
+ * - `slice(t, 0, { start: 1 })` on a 2D tensor selects row 0 and columns from 1.
+ */
+declare function slice(t: Tensor, ...ranges: SliceRange[]): Tensor;
+/**
+ * Gather values along an axis specified by indices.
+ *
+ * @param t - Input tensor
+ * @param indices - Indices to gather
+ * @param axis - Axis along which to gather
+ * @returns Gathered tensor
+ *
+ * @example
+ * ```ts
+ * const t = tensor([[1, 2], [3, 4], [5, 6]]);
+ * const indices = tensor([0, 2]);
+ * const result = gather(t, indices, 0);  // [[1, 2], [5, 6]]
+ * ```
+ */
+declare function gather(t: Tensor, indices: Tensor, axis: Axis): Tensor;
+
+/**
+ * Autograd module for automatic differentiation.
+ *
+ * Implements reverse-mode automatic differentiation (backpropagation)
+ * for `Tensor` operations.
+ *
+ * ## Gradient state
+ *
+ * A **module-level singleton** `gradEnabled` controls whether new
+ * operations record their backward graph.  Use {@link noGrad} to
+ * temporarily disable gradient tracking (e.g. during inference).
+ * `noGrad` only accepts **synchronous** callbacks — passing an async
+ * function will throw, because the flag would be restored before the
+ * async work completes.
+ *
+ * ## max / min backward — tie-breaking
+ *
+ * When multiple elements share the maximum (or minimum) value along the
+ * reduced axis, **all** tied positions receive gradient.  This means the
+ * gradient is *not* divided among ties — each tied element gets the full
+ * upstream gradient.  This matches PyTorch's behaviour and avoids the
+ * cost of counting ties, but callers should be aware that the
+ * "effective" gradient magnitude is multiplied by the tie count.
+ */
+
+type GradTensorOptions = {
+    readonly requiresGrad?: boolean;
+    readonly dtype?: Exclude<DType, "string">;
+};
+type BackwardFn = () => void;
+/**
+ * Tensor wrapper that records a computation graph for reverse-mode autodiff.
+ */
+declare class GradTensor {
+    readonly tensor: Tensor;
+    requiresGrad: boolean;
+    private _grad;
+    private readonly _prev;
+    private readonly _backward;
+    private constructor();
+    static create(args: {
+        readonly tensor: Tensor;
+        readonly requiresGrad: boolean;
+        readonly prev: readonly GradTensor[];
+        readonly backward: BackwardFn;
+    }): GradTensor;
+    static fromTensor(t: Tensor, options?: GradTensorOptions): GradTensor;
+    static scalar(value: number, options?: GradTensorOptions): GradTensor;
+    /**
+     * Get the shape of the underlying tensor.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get shape(): Shape;
+    /**
+     * Get the total number of elements.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get size(): number;
+    /**
+     * Get the number of dimensions.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get ndim(): number;
+    /**
+     * Get the data type of the underlying tensor.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get dtype(): DType;
+    /**
+     * Get the device where the tensor resides.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get device(): Tensor["device"];
+    /**
+     * Get the memory strides of the underlying tensor.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get strides(): readonly number[];
+    /**
+     * Get the offset into the underlying data buffer.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get offset(): number;
+    /**
+     * Get the underlying data buffer.
+     * Implements TensorLike interface for compatibility with Tensor.
+     */
+    get data(): TypedArray;
+    /**
+     * Get the accumulated gradient for this tensor.
+     * Returns null if no gradient has been computed yet.
+     */
+    get grad(): Tensor | null;
+    setGrad(grad: Tensor): void;
+    zeroGrad(): void;
+    detach(): GradTensor;
+    setRequiresGrad(value: boolean): void;
+    hasGrad(): boolean;
+    /** @internal */
+    accumulateGrad(grad: Tensor): void;
+    /**
+     * Backpropagate gradients from this node through the recorded graph.
+     */
+    backward(grad?: Tensor): void;
+    add(other: GradTensor): GradTensor;
+    sub(other: GradTensor): GradTensor;
+    mul(other: GradTensor): GradTensor;
+    neg(): GradTensor;
+    sum(axis?: Axis, keepdims?: boolean): GradTensor;
+    div(other: GradTensor): GradTensor;
+    pow(exponent: number): GradTensor;
+    sqrt(): GradTensor;
+    matmul(other: GradTensor): GradTensor;
+    relu(): GradTensor;
+    sigmoid(): GradTensor;
+    square(): GradTensor;
+    exp(): GradTensor;
+    log(): GradTensor;
+    tanh(): GradTensor;
+    slice(...args: SliceRange[]): GradTensor;
+    gather(indices: GradTensor, axis: Axis): GradTensor;
+    mean(axis?: Axis, keepdims?: boolean): GradTensor;
+    max(axis?: Axis, keepdims?: boolean): GradTensor;
+    /**
+     * Reshape the GradTensor to a new shape without copying data.
+     *
+     * Returns a new GradTensor with the specified shape. The underlying tensor
+     * is reshaped, and gradient computation is preserved through the reshape operation.
+     *
+     * @param newShape - The desired shape for the tensor
+     * @returns A new GradTensor with the specified shape
+     * @throws {ShapeError} If the new shape is incompatible with the tensor's size
+     *
+     * @example
+     * ```ts
+     * const t = parameter([1, 2, 3, 4, 5, 6]);
+     * const reshaped = t.reshape([2, 3]);
+     * console.log(reshaped.shape); // [2, 3]
+     * ```
+     */
+    reshape(newShape: Shape): GradTensor;
+    /**
+     * Flatten the GradTensor to a 1-dimensional array.
+     *
+     * Returns a new 1D GradTensor containing all elements.
+     *
+     * @returns A 1D GradTensor with shape [size]
+     *
+     * @example
+     * ```ts
+     * const matrix = parameter([[1, 2, 3], [4, 5, 6]]);
+     * const flat = matrix.flatten();
+     * console.log(flat.shape); // [6]
+     * ```
+     */
+    flatten(): GradTensor;
+    /**
+     * Create a view of the GradTensor with a different shape.
+     *
+     * Similar to reshape but uses the underlying tensor's view method.
+     *
+     * @param shape - The desired shape for the view
+     * @param strides - Optional custom strides
+     * @param offset - Optional offset into the data buffer
+     * @returns A new GradTensor view with the specified shape
+     */
+    view(shape: Shape, strides?: readonly number[], offset?: number): GradTensor;
+    transpose(axes?: readonly number[]): GradTensor;
+    min(axis?: Axis, keepdims?: boolean): GradTensor;
+    abs(): GradTensor;
+    clip(minVal: number, maxVal: number): GradTensor;
+    leakyRelu(negativeSlope?: number): GradTensor;
+    elu(alpha?: number): GradTensor;
+    gelu(): GradTensor;
+    /**
+     * Return a human-readable string representation of this GradTensor.
+     *
+     * Delegates to the underlying {@link Tensor.toString} and appends
+     * gradient metadata.
+     *
+     * @param maxElements - Maximum elements per dimension before summarizing (default: 6).
+     * @returns Formatted string representation
+     */
+    toString(maxElements?: number): string;
+}
+/**
+ * Create a GradTensor with requiresGrad=true.
+ */
+declare function parameter(data: number | number[] | number[][] | number[][][] | Tensor, options?: GradTensorOptions): GradTensor;
+/**
+ * Context manager to disable gradient calculation.
+ *
+ * **Important:** The callback must be synchronous. Passing an async function
+ * will cause `gradEnabled` to be restored before the awaited work finishes,
+ * silently breaking gradient tracking inside the async continuation.
+ *
+ * @throws {DeepboxError} If the callback returns a Promise (async function detected)
+ */
+declare function noGrad<T>(fn: () => T): T;
+/**
+ * Image to Column operation for GradTensor.
+ */
+declare function im2col(input: GradTensor, kernelSize: [number, number], stride: [number, number], padding: [number, number]): GradTensor;
+declare function softmax(input: GradTensor, axis?: number): GradTensor;
+declare function logSoftmax(input: GradTensor, axis?: number): GradTensor;
+declare function variance(input: GradTensor, axis?: number, correction?: number): GradTensor;
+declare function dropout(input: GradTensor, p?: number, training?: boolean): GradTensor;
+
+export { GradTensor as G, type SliceRange as S, type GradTensorOptions as a, softmax as b, dropout as d, gather as g, im2col as i, logSoftmax as l, noGrad as n, parameter as p, slice as s, variance as v };

package/dist/index-BbA2Gxfl.d.ts

@@ -0,0 +1,456 @@
+import { D as DType, a as Device, S as Shape } from './tensor-B96jjJLQ.js';
+import { T as Tensor } from './Tensor-g8mUClel.js';
+
+type RandomOptions = {
+    readonly dtype?: DType;
+    readonly device?: Device;
+};
+/**
+ * Set global random seed.
+ *
+ * @param seed - Random seed value (any finite number). The seed is coerced to a uint64
+ *               internally, so the same seed always produces the same sequence.
+ *
+ * @throws {InvalidParameterError} When seed is not finite (NaN or ±Infinity)
+ *
+ * @remarks
+ * - Setting a seed makes all random operations deterministic and reproducible.
+ * - The seed is truncated to uint64 range (0 to 2^64-1) for internal state.
+ * - Use {@link getSeed} to retrieve the currently set seed.
+ * - When no seed is set, random sampling uses a cryptographically secure RNG.
+ *   Seeded mode is deterministic and **not** intended for cryptographic use.
+ *
+ * @example
+ * ```js
+ * import { setSeed, rand } from 'deepbox/random';
+ *
+ * setSeed(42);
+ * const a = rand([5]);
+ * setSeed(42);
+ * const b = rand([5]);
+ * // a and b contain identical values
+ * ```
+ */
+declare function setSeed(seed: number): void;
+/**
+ * Get current random seed.
+ *
+ * @returns Current seed value or undefined if not set
+ *
+ * @example
+ * ```js
+ * import { setSeed, getSeed } from 'deepbox/random';
+ *
+ * setSeed(12345);
+ * console.log(getSeed()); // 12345
+ * ```
+ */
+declare function getSeed(): number | undefined;
+/**
+ * Clear the current random seed and revert to cryptographically secure randomness.
+ *
+ * @remarks
+ * - After calling this, random sampling uses `crypto.getRandomValues`.
+ * - Use this to leave deterministic mode after {@link setSeed}.
+ *
+ * @example
+ * ```js
+ * import { clearSeed, rand } from 'deepbox/random';
+ *
+ * clearSeed();
+ * const x = rand([3]);  // cryptographically secure randomness
+ * ```
+ */
+declare function clearSeed(): void;
+/**
+ * Random values in half-open interval [0, 1).
+ *
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @remarks
+ * - Values are uniformly distributed in [0, 1) (inclusive lower, exclusive upper bound).
+ * - Uses deterministic PRNG when seed is set via {@link setSeed}.
+ * - Default dtype is float32; use float64 for higher precision.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { rand, setSeed } from 'deepbox/random';
+ *
+ * const x = rand([2, 3]);  // 2x3 matrix of random values
+ *
+ * // Deterministic generation
+ * setSeed(42);
+ * const a = rand([5]);
+ * setSeed(42);
+ * const b = rand([5]);
+ * // a and b are identical
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.rand.html | NumPy random.rand}
+ */
+declare function rand(shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from standard normal distribution.
+ *
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @remarks
+ * - Uses Box-Muller transform to generate normally distributed values.
+ * - Mean = 0, standard deviation = 1.
+ * - All values are finite (no infinities from tail behavior).
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { randn } from 'deepbox/random';
+ *
+ * const x = randn([2, 3]);  // 2x3 matrix of normal random values
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.randn.html | NumPy random.randn}
+ */
+declare function randn(shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random integers in half-open interval [low, high).
+ *
+ * @param low - Lowest integer (inclusive)
+ * @param high - Highest integer (exclusive)
+ * @param shape - Output shape
+ * @param opts - Options (dtype, device)
+ *
+ * @throws {InvalidParameterError} When low or high is not finite
+ * @throws {InvalidParameterError} When low or high is not an integer
+ * @throws {InvalidParameterError} When high <= low
+ *
+ * @remarks
+ * - Generates integers uniformly in [low, high) range.
+ * - Both low and high must be safe integers (within ±2^53-1).
+ * - dtype must be int32 or int64; int32 output requires bounds within int32 range.
+ * - Deterministic when seed is set via {@link setSeed}.
+ *
+ * @example
+ * ```js
+ * import { randint } from 'deepbox/random';
+ *
+ * const x = randint(0, 10, [5]);  // 5 random integers from 0 to 9
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.randint.html | NumPy random.randint}
+ */
+declare function randint(low: number, high: number, shape: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from continuous uniform distribution.
+ *
+ * @param low - Lower boundary (default: 0)
+ * @param high - Upper boundary (default: 1)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When low or high is not finite
+ * @throws {InvalidParameterError} When high < low
+ *
+ * @remarks
+ * - Values are uniformly distributed in [low, high).
+ * - For very large ranges, floating-point precision may affect uniformity.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { uniform } from 'deepbox/random';
+ *
+ * const x = uniform(-1, 1, [3, 3]);  // Values between -1 and 1
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.uniform.html | NumPy random.uniform}
+ */
+declare function uniform(low?: number, high?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from normal (Gaussian) distribution.
+ *
+ * @param mean - Mean of distribution (default: 0)
+ * @param std - Standard deviation (default: 1)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When mean or std is not finite
+ * @throws {InvalidParameterError} When std < 0
+ *
+ * @remarks
+ * - Uses Box-Muller transform internally.
+ * - All values are finite due to RNG resolution (no infinities from log(0)).
+ * - std=0 produces constant values equal to mean.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { normal } from 'deepbox/random';
+ *
+ * const x = normal(0, 2, [100]);  // Mean 0, std 2
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.normal.html | NumPy random.normal}
+ */
+declare function normal(mean?: number, std?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from binomial distribution.
+ *
+ * @param n - Number of trials (non-negative integer)
+ * @param p - Probability of success (in [0, 1])
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When n is not finite, not an integer, or < 0
+ * @throws {InvalidParameterError} When p is not finite or not in [0, 1]
+ *
+ * @remarks
+ * - Generates number of successes in n independent Bernoulli trials.
+ * - Uses an exact geometric waiting-time method for small means and
+ *   a mode-centered chop-down inversion for larger means.
+ * - Results are in range [0, n].
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only int32 and int64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { binomial } from 'deepbox/random';
+ *
+ * const x = binomial(10, 0.5, [100]);  // 10 coin flips, 100 times
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.binomial.html | NumPy random.binomial}
+ */
+declare function binomial(n: number, p: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from Poisson distribution.
+ *
+ * @param lambda - Expected number of events (rate, must be >= 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When lambda is not finite or < 0
+ *
+ * @remarks
+ * - Uses Knuth's method for lambda < 30, transformed rejection for lambda >= 30.
+ * - Stable and efficient for all lambda values (tested up to lambda=1000+).
+ * - lambda=0 always produces 0.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only int32 and int64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { poisson } from 'deepbox/random';
+ *
+ * const x = poisson(5, [100]);  // Rate = 5 events
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.poisson.html | NumPy random.poisson}
+ */
+declare function poisson(lambda: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from exponential distribution.
+ *
+ * @param scale - Scale parameter (1/lambda, default: 1, must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When scale is not finite or <= 0
+ *
+ * @remarks
+ * - Uses inverse transform sampling: -scale * log(U).
+ * - All values are positive (u=0 is avoided to prevent infinities).
+ * - Mean = scale, variance = scale^2.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { exponential } from 'deepbox/random';
+ *
+ * const x = exponential(2, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.exponential.html | NumPy random.exponential}
+ */
+declare function exponential(scale?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from gamma distribution.
+ *
+ * @param shape_param - Shape parameter (k, must be > 0)
+ * @param scale - Scale parameter (theta, default: 1, must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When shape_param is not finite or <= 0
+ * @throws {InvalidParameterError} When scale is not finite or <= 0
+ *
+ * @remarks
+ * - Uses Marsaglia and Tsang's method (2000) for efficient sampling.
+ * - All values are positive.
+ * - Mean = shape_param * scale, variance = shape_param * scale^2.
+ * - For shape_param < 1, uses a transformation to handle the case.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { gamma } from 'deepbox/random';
+ *
+ * const x = gamma(2, 2, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.gamma.html | NumPy random.gamma}
+ */
+declare function gamma(shape_param: number, scale?: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random samples from beta distribution.
+ *
+ * @param alpha - Alpha parameter (must be > 0)
+ * @param beta_param - Beta parameter (must be > 0)
+ * @param shape - Output shape
+ * @param opts - Options
+ *
+ * @throws {InvalidParameterError} When alpha is not finite or <= 0
+ * @throws {InvalidParameterError} When beta_param is not finite or <= 0
+ *
+ * @remarks
+ * - Uses ratio of two gamma distributions: X / (X + Y).
+ * - All values are in the open interval (0, 1) up to floating-point rounding.
+ * - Mean = alpha / (alpha + beta), useful for modeling proportions.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Only float32 and float64 dtypes are supported.
+ *
+ * @example
+ * ```js
+ * import { beta } from 'deepbox/random';
+ *
+ * const x = beta(2, 5, [100]);
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.beta.html | NumPy random.beta}
+ */
+declare function beta(alpha: number, beta_param: number, shape?: Shape, opts?: RandomOptions): Tensor;
+/**
+ * Random sample from array.
+ *
+ * @param a - Input array or integer (if integer, sample from arange(a))
+ * @param size - Number of samples or output shape
+ * @param replace - Whether to sample with replacement (default: true)
+ * @param p - Optional probability weights for weighted sampling
+ *
+ * @throws {InvalidParameterError} When population size is invalid (not finite, not integer, or < 0)
+ * @throws {InvalidParameterError} When size > population and replace is false
+ * @throws {InvalidParameterError} When tensor is not contiguous (offset !== 0 or non-standard strides)
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - Input tensor must be contiguous (no slicing/striding).
+ * - With replacement: can sample more elements than population size.
+ * - Without replacement: size must be <= population size.
+ * - Does NOT modify the input tensor (returns a new tensor).
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - If `a` is a number, the population is `0..a-1` and output dtype is int32.
+ * - Numeric populations are limited to `a <= 2^31` for int32 output.
+ *
+ * @example
+ * ```js
+ * import { choice, tensor } from 'deepbox/random';
+ *
+ * const x = tensor([1, 2, 3, 4, 5]);
+ * const sample = choice(x, 3);  // Pick 3 elements with replacement
+ *
+ * // Without replacement
+ * const unique = choice(x, 3, false);  // All different elements
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.choice.html | NumPy random.choice}
+ */
+declare function choice(a: Tensor | number, size?: number | Shape, replace?: boolean, p?: Tensor): Tensor;
+/**
+ * Randomly shuffle array in-place.
+ *
+ * @param x - Input tensor (**MODIFIED IN-PLACE**)
+ *
+ * @throws {InvalidParameterError} When tensor is not contiguous (offset !== 0 or non-standard strides)
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - **WARNING: This function mutates the input tensor directly.**
+ * - Uses Fisher-Yates shuffle algorithm (O(n) time, optimal).
+ * - Input tensor must be contiguous (no slicing/striding).
+ * - All elements are preserved, only their order changes.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - If you need a shuffled copy without mutation, use {@link permutation} instead.
+ *
+ * @example
+ * ```js
+ * import { shuffle, tensor } from 'deepbox/random';
+ *
+ * const x = tensor([1, 2, 3, 4, 5]);
+ * shuffle(x);  // x is now shuffled IN-PLACE
+ * console.log(x);  // e.g., [3, 1, 5, 2, 4]
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.shuffle.html | NumPy random.shuffle}
+ */
+declare function shuffle(x: Tensor): void;
+/**
+ * Return random permutation of array.
+ *
+ * @param x - Input tensor or integer
+ *
+ * @throws {DTypeError} When input tensor has string dtype
+ *
+ * @remarks
+ * - Returns a NEW tensor (does NOT modify input).
+ * - If x is an integer, returns permutation of arange(x).
+ * - If x is a tensor, returns a shuffled copy with the same shape.
+ * - Tensor inputs must be contiguous (no slicing/striding).
+ * - Uses Fisher-Yates shuffle algorithm internally.
+ * - Deterministic when seed is set via {@link setSeed}.
+ * - Numeric input is limited to `x <= 2^31` for int32 output.
+ *
+ * @example
+ * ```js
+ * import { permutation, tensor } from 'deepbox/random';
+ *
+ * // Permutation of integers
+ * const x = permutation(10);  // Random permutation of [0...9]
+ *
+ * // Permutation of tensor (does not modify original)
+ * const original = tensor([1, 2, 3, 4, 5]);
+ * const shuffled = permutation(original);
+ * // original is unchanged
+ * ```
+ *
+ * @see {@link https://numpy.org/doc/stable/reference/random/generated/numpy.random.permutation.html | NumPy random.permutation}
+ */
+declare function permutation(x: Tensor | number): Tensor;
+
+type index_RandomOptions = RandomOptions;
+declare const index_beta: typeof beta;
+declare const index_binomial: typeof binomial;
+declare const index_choice: typeof choice;
+declare const index_clearSeed: typeof clearSeed;
+declare const index_exponential: typeof exponential;
+declare const index_gamma: typeof gamma;
+declare const index_getSeed: typeof getSeed;
+declare const index_normal: typeof normal;
+declare const index_permutation: typeof permutation;
+declare const index_poisson: typeof poisson;
+declare const index_rand: typeof rand;
+declare const index_randint: typeof randint;
+declare const index_randn: typeof randn;
+declare const index_setSeed: typeof setSeed;
+declare const index_shuffle: typeof shuffle;
+declare const index_uniform: typeof uniform;
+declare namespace index {
+  export { type index_RandomOptions as RandomOptions, index_beta as beta, index_binomial as binomial, index_choice as choice, index_clearSeed as clearSeed, index_exponential as exponential, index_gamma as gamma, index_getSeed as getSeed, index_normal as normal, index_permutation as permutation, index_poisson as poisson, index_rand as rand, index_randint as randint, index_randn as randn, index_setSeed as setSeed, index_shuffle as shuffle, index_uniform as uniform };
+}
+
+export { type RandomOptions as R, randn as a, randint as b, clearSeed as c, binomial as d, exponential as e, gamma as f, getSeed as g, beta as h, index as i, choice as j, shuffle as k, permutation as l, normal as n, poisson as p, rand as r, setSeed as s, uniform as u };