@dniskav/neuron 0.3.0 → 0.3.1

package/README.md

@@ -3,7 +3,7 @@
 
 A minimal, dependency-free neural network library built from scratch in TypeScript. Designed for learning and experimentation — every line of math is readable.
 
-Each class is a building block for the next: from a single neuron to a full Transformer with causal attention. v0.3.0 adds classical ML, unsupervised learning, generative models, autograd, and training utilities — all in pure TypeScript, zero dependencies.
+Each class is a building block for the next: from a single neuron to a full Transformer with causal attention. Includes classical ML, unsupervised learning, generative models, embeddings, and autograd — all in pure TypeScript, zero dependencies.
 
 ```mermaid
 graph TD
@@ -126,6 +126,17 @@ graph TD
 |--------|-------------|
 | `Value` | Scalar autograd node. Builds a computational graph and propagates gradients with `.backward()`. Inspired by micrograd. |
 
+### Embeddings
+
+| Export | Description |
+|--------|-------------|
+| `Word2Vec` | Learns word embeddings via Skip-gram or CBOW. Full-softmax, cosine similarity, analogies (`king - man + woman ≈ queen`). |
+| `TSNE` | t-SNE dimensionality reduction. Binary-search perplexity, Student-t kernel, KL gradient, early exaggeration. |
+| `PositionalEncoding` | Sinusoidal positional encoding (Vaswani et al.). Static — no parameters, generalizes to unseen lengths. |
+| `LearnedPositionalEncoding` | Trainable positional encoding. Xavier-initialized, learnable up to a fixed `maxSeqLen`. |
+| `ContrastiveLearning` | SimCLR-style self-supervised learning. NT-Xent loss, encoder + projection head, temperature τ. |
+| `Augmenter` | Data augmentation helpers for contrastive pairs: Gaussian noise, feature dropout, `makePair()`. |
+
 ### Activations & math
 
 | Export | Description |
@@ -396,6 +407,79 @@ const { mu, logVar } = vae.encode(image);  // encode → distribution params
 const z = vae.reparametrize(mu, logVar);   // sample z ~ N(μ, σ²)
 ```
 
+### Word2Vec — aprende embeddings de palabras
+
+```ts
+import { Word2Vec } from "@dniskav/neuron";
+
+const w2v = new Word2Vec(64, { model: 'skipgram', windowSize: 2 });
+
+const corpus = [
+  ["the", "king", "rules", "the", "kingdom"],
+  ["the", "queen", "rules", "the", "land"],
+  ["man", "and", "woman", "are", "human"],
+];
+
+w2v.buildVocab(corpus);
+w2v.train(corpus, 0.05, 200);
+
+console.log(w2v.similarity("king", "queen")); // high
+console.log(w2v.mostSimilar("king", 3));
+// [{ word: 'queen', score: 0.91 }, ...]
+
+// Vector arithmetic: king - man + woman ≈ queen
+console.log(w2v.analogy("king", "man", "woman", 1));
+// [{ word: 'queen', score: 0.87 }]
+```
+
+### t-SNE — visualiza embeddings en 2D
+
+```ts
+import { TSNE } from "@dniskav/neuron";
+
+// Reduce 128-dim embeddings → 2D for plotting
+const tsne = new TSNE({ perplexity: 30, nIter: 1000, seed: 42 });
+const points2D = tsne.fitTransform(embeddings128D); // [n][2]
+
+console.log(tsne.kl()); // KL divergence — lower is better
+// Plot points2D with any charting library
+```
+
+### PositionalEncoding — orden sin parámetros
+
+```ts
+import { PositionalEncoding, LearnedPositionalEncoding } from "@dniskav/neuron";
+
+// Sinusoidal — deterministic, no training needed
+const pe = PositionalEncoding.encodeSequence(512, 128); // [512][128]
+const withPos = PositionalEncoding.apply(tokenEmbeddings); // add PE to embeddings
+
+// Learned — trainable, fixed maxSeqLen
+const lpe = new LearnedPositionalEncoding(512, 128);
+const withLearnedPos = lpe.apply(tokenEmbeddings);
+lpe.update(gradients, 0.001); // update during backprop
+```
+
+### ContrastiveLearning — representaciones sin etiquetas
+
+```ts
+import { ContrastiveLearning, Augmenter } from "@dniskav/neuron";
+
+// Encoder: 128 → [256, 128] → 64 latent, projection head: 64 → 32
+const cl = new ContrastiveLearning(128, [256, 128], 64, { temperature: 0.5 });
+
+// Create positive pairs from unlabeled data (two augmented views per sample)
+const pairs = unlabeledData.map(x => Augmenter.makePair(x));
+
+for (let step = 0; step < 1000; step++) {
+  const loss = cl.trainStep(pairs, 0.001);
+  if (step % 100 === 0) console.log(`step ${step}: ${loss.toFixed(4)}`);
+}
+
+// Use encoder for downstream tasks (classification, clustering, etc.)
+const representation = cl.encode(newSample); // 64-dim vector
+```
+
 ### Value / Tape — automatic differentiation
 
 ```ts
@@ -596,6 +680,9 @@ If you are an AI agent or LLM working with this codebase, read [AGENTS.md](AGENT
 
 ## Changelog
 
+### v0.3.1
+- **New — Embeddings:** `Word2Vec` (Skip-gram + CBOW, full-softmax, cosine similarity, analogies), `TSNE` (binary-search perplexity, Student-t kernel, KL gradient, early exaggeration, seeded PRNG), `PositionalEncoding` (sinusoidal, Vaswani et al.), `LearnedPositionalEncoding` (trainable), `ContrastiveLearning` (NT-Xent, SimCLR encoder + projection head), `Augmenter` (noise, feature dropout, `makePair`)
+
 ### v0.3.0
 - **New — Classical ML:** `Perceptron`, `LinearRegression` (normal equation + GD), `LogisticRegression`, `SoftmaxRegression`, `GaussianNaiveBayes`, `DecisionTree` (CART, Gini/MSE)
 - **New — Unsupervised:** `KMeans` (K-Means++ init), `PCA` (power iteration + Hotelling deflation), `SOM` (Kohonen map), `HopfieldNetwork` (Hebbian storage + energy), `Autoencoder`

package/dist/index.d.mts

@@ -893,6 +893,123 @@ declare class TCN {
     train(sequence: number[][], targets: number[][], lr: number): number;
 }
 
+type Word2VecModel = 'skipgram' | 'cbow';
+interface Word2VecOptions {
+    /** Size of the sliding context window on each side of the center word. Default 2. */
+    windowSize?: number;
+    /** Training architecture. Default 'skipgram'. */
+    model?: Word2VecModel;
+    /** Ignore words with corpus frequency below this threshold. Default 1. */
+    minCount?: number;
+}
+declare class Word2Vec {
+    /** Learned word vectors, shape [vocabSize][embeddingDim]. */
+    embeddings: number[][];
+    /** Maps each vocabulary word to its integer index. */
+    vocab: Map<string, number>;
+    vocabSize: number;
+    embeddingDim: number;
+    private _indexToWord;
+    private _W2;
+    private _windowSize;
+    private _model;
+    private _minCount;
+    private _trained;
+    constructor(embeddingDim?: number, options?: Word2VecOptions);
+    buildVocab(sentences: string[][]): void;
+    static tokenize(text: string): string[];
+    train(sentences: string[][], lr?: number, epochs?: number): number[];
+    getEmbedding(word: string): number[];
+    similarity(word1: string, word2: string): number;
+    mostSimilar(word: string, topK?: number): {
+        word: string;
+        score: number;
+    }[];
+    analogy(positive1: string, negative: string, positive2: string, topK?: number): {
+        word: string;
+        score: number;
+    }[];
+    private _skipgramStep;
+    private _cbowStep;
+    private _hiddenToScores;
+    private _nearestByVector;
+    private _cosine;
+}
+
+interface TSNEOptions {
+    /** Dimensionality of the output embedding. Default 2. */
+    nComponents?: number;
+    /**
+     * Perplexity — loosely controls the effective number of neighbors considered
+     * for each point. Typical values: 5–50. Default 30.
+     * Must be less than the number of data points.
+     */
+    perplexity?: number;
+    /** Learning rate for gradient descent. Default 200. */
+    lr?: number;
+    /** Number of gradient-descent iterations. Default 1000. */
+    nIter?: number;
+    /**
+     * Seed for the pseudo-random number generator.
+     * Set to any integer for reproducible results. Default uses Math.random.
+     */
+    seed?: number;
+}
+declare class TSNE {
+    /** Result of the embedding, shape [n][nComponents]. Available after fit(). */
+    embedding: number[][];
+    private readonly _nComponents;
+    private readonly _perplexity;
+    private readonly _lr;
+    private readonly _nIter;
+    private readonly _seed;
+    private _klDivergence;
+    private _P;
+    constructor(options?: TSNEOptions);
+    fit(X: number[][]): void;
+    fitTransform(X: number[][]): number[][];
+    kl(): number;
+    private _computePcond;
+}
+
+declare class PositionalEncoding {
+    static encode(pos: number, dModel: number): number[];
+    static encodeSequence(seqLen: number, dModel: number): number[][];
+    static apply(embeddings: number[][], seqLen?: number): number[][];
+}
+declare class LearnedPositionalEncoding {
+    readonly maxSeqLen: number;
+    readonly dModel: number;
+    weights: number[][];
+    constructor(maxSeqLen: number, dModel: number);
+    getEncoding(pos: number): number[];
+    apply(embeddings: number[][], seqLen?: number): number[][];
+    update(dWeights: number[][], lr: number): void;
+}
+
+declare class Augmenter {
+    static addNoise(x: number[], sigma?: number): number[];
+    static dropoutFeatures(x: number[], rate?: number): number[];
+    static augment(x: number[], noiseStd?: number, dropRate?: number): number[];
+    static makePair(x: number[]): [number[], number[]];
+}
+declare class ContrastiveLearning {
+    encoder: NetworkN;
+    projectionHead: NetworkN;
+    temperature: number;
+    constructor(inputSize: number, encoderHidden: number[], projectionDim: number, options?: {
+        temperature?: number;
+        encoderOptions?: NetworkNOptions;
+    });
+    encode(x: number[]): number[];
+    project(x: number[]): number[];
+    static cosineSimilarity(a: number[], b: number[]): number;
+    computeLoss(pairs: [number[], number[]][]): number;
+    trainStep(pairs: [number[], number[]][], lr: number): number;
+    private _forwardProjections;
+    private _ntXentLoss;
+}
+
 declare class GAN {
     readonly generator: NetworkN;
     readonly discriminator: NetworkN;
@@ -1062,4 +1179,4 @@ declare class DataAugmentation {
     };
 }
 
-export { type Activation, Adam, AttentionHead, Autoencoder, BatchNorm, BiasVector, CausalConv1D, ClipOptimizer, ClippedOptimizerFactory, Conv1D, Conv2D, DataAugmentation, DataLoader, type DataPair, DecisionTree, Dropout, EarlyStopping, EmbeddingMatrix, Flatten, GAN, GRULayer, GaussianNaiveBayes, HopfieldNetwork, KMeans, type KMeansOptions, LRScheduler, LSTMLayer, Layer, LayerNorm, LinearRegression, LogisticRegression, LossPlotter, MaxPool2D, ModelSaver, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, PCA, Perceptron, RNN, SGD, SOM, type SOMOptions, Seq2Seq, type Serializable, SoftmaxRegression, TCN, type TrainDataset, type TrainMetrics, type TrainableNetwork, type TrainableNetworkWithWeights, Trainer, type TrainerOptions, TransformerBlock, type TransformerBlockOptions, VAE, Value, WeightInspector, WeightMatrix, type WeightStats, accuracy, auc, classificationReport, confusionMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, defaultOptimizer, elu, f1Score, leakyRelu, linear, mae, makeElu, makeLeakyRelu, matMul, mse, mseDelta, perplexity, precision, printConfusionMatrix, r2Score, recall, relu, rmse, rocCurve, sigmoid, softmax, softmaxBackward, tanh, transpose, validate2DArray, validateArray, validateArrayMinLength, validateNumber };
+export { type Activation, Adam, AttentionHead, Augmenter, Autoencoder, BatchNorm, BiasVector, CausalConv1D, ClipOptimizer, ClippedOptimizerFactory, ContrastiveLearning, Conv1D, Conv2D, DataAugmentation, DataLoader, type DataPair, DecisionTree, Dropout, EarlyStopping, EmbeddingMatrix, Flatten, GAN, GRULayer, GaussianNaiveBayes, HopfieldNetwork, KMeans, type KMeansOptions, LRScheduler, LSTMLayer, Layer, LayerNorm, LearnedPositionalEncoding, LinearRegression, LogisticRegression, LossPlotter, MaxPool2D, ModelSaver, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, PCA, Perceptron, PositionalEncoding, RNN, SGD, SOM, type SOMOptions, Seq2Seq, type Serializable, SoftmaxRegression, TCN, TSNE, type TSNEOptions, type TrainDataset, type TrainMetrics, type TrainableNetwork, type TrainableNetworkWithWeights, Trainer, type TrainerOptions, TransformerBlock, type TransformerBlockOptions, VAE, Value, WeightInspector, WeightMatrix, type WeightStats, Word2Vec, type Word2VecModel, type Word2VecOptions, accuracy, auc, classificationReport, confusionMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, defaultOptimizer, elu, f1Score, leakyRelu, linear, mae, makeElu, makeLeakyRelu, matMul, mse, mseDelta, perplexity, precision, printConfusionMatrix, r2Score, recall, relu, rmse, rocCurve, sigmoid, softmax, softmaxBackward, tanh, transpose, validate2DArray, validateArray, validateArrayMinLength, validateNumber };

package/dist/index.d.ts

@@ -893,6 +893,123 @@ declare class TCN {
     train(sequence: number[][], targets: number[][], lr: number): number;
 }
 
+type Word2VecModel = 'skipgram' | 'cbow';
+interface Word2VecOptions {
+    /** Size of the sliding context window on each side of the center word. Default 2. */
+    windowSize?: number;
+    /** Training architecture. Default 'skipgram'. */
+    model?: Word2VecModel;
+    /** Ignore words with corpus frequency below this threshold. Default 1. */
+    minCount?: number;
+}
+declare class Word2Vec {
+    /** Learned word vectors, shape [vocabSize][embeddingDim]. */
+    embeddings: number[][];
+    /** Maps each vocabulary word to its integer index. */
+    vocab: Map<string, number>;
+    vocabSize: number;
+    embeddingDim: number;
+    private _indexToWord;
+    private _W2;
+    private _windowSize;
+    private _model;
+    private _minCount;
+    private _trained;
+    constructor(embeddingDim?: number, options?: Word2VecOptions);
+    buildVocab(sentences: string[][]): void;
+    static tokenize(text: string): string[];
+    train(sentences: string[][], lr?: number, epochs?: number): number[];
+    getEmbedding(word: string): number[];
+    similarity(word1: string, word2: string): number;
+    mostSimilar(word: string, topK?: number): {
+        word: string;
+        score: number;
+    }[];
+    analogy(positive1: string, negative: string, positive2: string, topK?: number): {
+        word: string;
+        score: number;
+    }[];
+    private _skipgramStep;
+    private _cbowStep;
+    private _hiddenToScores;
+    private _nearestByVector;
+    private _cosine;
+}
+
+interface TSNEOptions {
+    /** Dimensionality of the output embedding. Default 2. */
+    nComponents?: number;
+    /**
+     * Perplexity — loosely controls the effective number of neighbors considered
+     * for each point. Typical values: 5–50. Default 30.
+     * Must be less than the number of data points.
+     */
+    perplexity?: number;
+    /** Learning rate for gradient descent. Default 200. */
+    lr?: number;
+    /** Number of gradient-descent iterations. Default 1000. */
+    nIter?: number;
+    /**
+     * Seed for the pseudo-random number generator.
+     * Set to any integer for reproducible results. Default uses Math.random.
+     */
+    seed?: number;
+}
+declare class TSNE {
+    /** Result of the embedding, shape [n][nComponents]. Available after fit(). */
+    embedding: number[][];
+    private readonly _nComponents;
+    private readonly _perplexity;
+    private readonly _lr;
+    private readonly _nIter;
+    private readonly _seed;
+    private _klDivergence;
+    private _P;
+    constructor(options?: TSNEOptions);
+    fit(X: number[][]): void;
+    fitTransform(X: number[][]): number[][];
+    kl(): number;
+    private _computePcond;
+}
+
+declare class PositionalEncoding {
+    static encode(pos: number, dModel: number): number[];
+    static encodeSequence(seqLen: number, dModel: number): number[][];
+    static apply(embeddings: number[][], seqLen?: number): number[][];
+}
+declare class LearnedPositionalEncoding {
+    readonly maxSeqLen: number;
+    readonly dModel: number;
+    weights: number[][];
+    constructor(maxSeqLen: number, dModel: number);
+    getEncoding(pos: number): number[];
+    apply(embeddings: number[][], seqLen?: number): number[][];
+    update(dWeights: number[][], lr: number): void;
+}
+
+declare class Augmenter {
+    static addNoise(x: number[], sigma?: number): number[];
+    static dropoutFeatures(x: number[], rate?: number): number[];
+    static augment(x: number[], noiseStd?: number, dropRate?: number): number[];
+    static makePair(x: number[]): [number[], number[]];
+}
+declare class ContrastiveLearning {
+    encoder: NetworkN;
+    projectionHead: NetworkN;
+    temperature: number;
+    constructor(inputSize: number, encoderHidden: number[], projectionDim: number, options?: {
+        temperature?: number;
+        encoderOptions?: NetworkNOptions;
+    });
+    encode(x: number[]): number[];
+    project(x: number[]): number[];
+    static cosineSimilarity(a: number[], b: number[]): number;
+    computeLoss(pairs: [number[], number[]][]): number;
+    trainStep(pairs: [number[], number[]][], lr: number): number;
+    private _forwardProjections;
+    private _ntXentLoss;
+}
+
 declare class GAN {
     readonly generator: NetworkN;
     readonly discriminator: NetworkN;
@@ -1062,4 +1179,4 @@ declare class DataAugmentation {
     };
 }
 
-export { type Activation, Adam, AttentionHead, Autoencoder, BatchNorm, BiasVector, CausalConv1D, ClipOptimizer, ClippedOptimizerFactory, Conv1D, Conv2D, DataAugmentation, DataLoader, type DataPair, DecisionTree, Dropout, EarlyStopping, EmbeddingMatrix, Flatten, GAN, GRULayer, GaussianNaiveBayes, HopfieldNetwork, KMeans, type KMeansOptions, LRScheduler, LSTMLayer, Layer, LayerNorm, LinearRegression, LogisticRegression, LossPlotter, MaxPool2D, ModelSaver, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, PCA, Perceptron, RNN, SGD, SOM, type SOMOptions, Seq2Seq, type Serializable, SoftmaxRegression, TCN, type TrainDataset, type TrainMetrics, type TrainableNetwork, type TrainableNetworkWithWeights, Trainer, type TrainerOptions, TransformerBlock, type TransformerBlockOptions, VAE, Value, WeightInspector, WeightMatrix, type WeightStats, accuracy, auc, classificationReport, confusionMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, defaultOptimizer, elu, f1Score, leakyRelu, linear, mae, makeElu, makeLeakyRelu, matMul, mse, mseDelta, perplexity, precision, printConfusionMatrix, r2Score, recall, relu, rmse, rocCurve, sigmoid, softmax, softmaxBackward, tanh, transpose, validate2DArray, validateArray, validateArrayMinLength, validateNumber };
+export { type Activation, Adam, AttentionHead, Augmenter, Autoencoder, BatchNorm, BiasVector, CausalConv1D, ClipOptimizer, ClippedOptimizerFactory, ContrastiveLearning, Conv1D, Conv2D, DataAugmentation, DataLoader, type DataPair, DecisionTree, Dropout, EarlyStopping, EmbeddingMatrix, Flatten, GAN, GRULayer, GaussianNaiveBayes, HopfieldNetwork, KMeans, type KMeansOptions, LRScheduler, LSTMLayer, Layer, LayerNorm, LearnedPositionalEncoding, LinearRegression, LogisticRegression, LossPlotter, MaxPool2D, ModelSaver, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, PCA, Perceptron, PositionalEncoding, RNN, SGD, SOM, type SOMOptions, Seq2Seq, type Serializable, SoftmaxRegression, TCN, TSNE, type TSNEOptions, type TrainDataset, type TrainMetrics, type TrainableNetwork, type TrainableNetworkWithWeights, Trainer, type TrainerOptions, TransformerBlock, type TransformerBlockOptions, VAE, Value, WeightInspector, WeightMatrix, type WeightStats, Word2Vec, type Word2VecModel, type Word2VecOptions, accuracy, auc, classificationReport, confusionMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, defaultOptimizer, elu, f1Score, leakyRelu, linear, mae, makeElu, makeLeakyRelu, matMul, mse, mseDelta, perplexity, precision, printConfusionMatrix, r2Score, recall, relu, rmse, rocCurve, sigmoid, softmax, softmaxBackward, tanh, transpose, validate2DArray, validateArray, validateArrayMinLength, validateNumber };