deepbox 0.1.0

package/dist/index-DIp_RrRt.d.ts

@@ -0,0 +1,242 @@
+import { A as Axis, D as DType, S as Shape, b as TypedArray } from './tensor-B96jjJLQ.js';
+import { T as Tensor } from './Tensor-g8mUClel.js';
+
+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 };