grnexus 1.0.2

data/README.md

@@ -0,0 +1,1105 @@
+# GRNexus
+
+[![Gem Version](https://badge.fury.io/rb/grnexus.svg)](https://badge.fury.io/rb/grnexus)
+[![License](https://img.shields.io/badge/license-GPL--3.0-green.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-3.0+-red.svg)](https://www.ruby-lang.org)
+
+**High-Performance Cross-Language Neural Network Framework for Ruby**
+
+GRNexus is a revolutionary neural network library that combines Ruby's elegance with native C acceleration. Train models in Ruby and deploy them anywhere - even in Python. With 10-100x performance improvements over pure Ruby implementations, GRNexus brings enterprise-grade machine learning to the Ruby ecosystem.
+
+---
+
+## Table of Contents
+
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Deep Learning](#deep-learning)
+- [Classical Machine Learning](#classical-machine-learning)
+- [Text Processing & NLP](#text-processing--nlp)
+- [Numeric Processing](#numeric-processing)
+- [Advanced Features](#advanced-features)
+- [API Reference](#api-reference)
+- [Documentation](#documentation)
+- [License](#license)
+
+---
+
+## Key Features
+
+### Performance & Architecture
+- **Native C Acceleration**: 10-100x faster than pure Ruby implementations via FFI
+- **Cross-Language Compatibility**: Train in Ruby, deploy in Python (and vice versa)
+- **Zero Heavy Dependencies**: No TensorFlow or PyTorch required
+- **Cross-Platform**: Windows, macOS, and Linux support
+
+### Deep Learning Capabilities
+- **35+ Activation Functions**: GELU, Swish, Mish, Snake, and more
+- **12+ Layer Types**: Dense, Conv2D, LSTM, GRU, BatchNorm, Dropout, Embedding
+- **Smart Training**: EarlyStopping, ModelCheckpoint, ReduceLR, LearningRateScheduler
+- **Model Inspection**: Analyze saved models without loading them
+
+### Classical Machine Learning
+- **K-Nearest Neighbors (KNN)**: Fast classification with native C implementation
+- **K-Means Clustering**: Efficient unsupervised learning
+- **Linear Regression**: Optimized least squares regression
+- **Logistic Regression**: Binary and multiclass classification
+- **Naive Bayes**: Probabilistic classification
+
+### Natural Language Processing
+- **Vocabulary Management**: Tokenization with frequency filtering
+- **Text Vectorization**: TF-IDF and count vectorization
+- **Word Embeddings**: Xavier-initialized embeddings for NLP
+- **Document Similarity**: Cosine similarity and text analysis
+
+### Numeric Operations
+- **Statistical Functions**: Mean, std, variance, correlation
+- **Normalization**: Z-score, MinMax, L1, L2
+- **Time Series**: Moving average, differences, integration
+- **Array Operations**: 40+ operations for data manipulation
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'grnexus'
+```
+
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install grnexus
+```
+
+---
+
+## Quick Start
+
+### XOR Problem - Neural Network Basics
+
+```ruby
+require 'grnexus'
+
+# XOR dataset
+x_train = [[0, 0], [0, 1], [1, 0], [1, 1]]
+y_train = [[0], [1], [1], [0]]
+
+# Build neural network
+model = GRNexus::NeuralNetwork.new(loss: 'mse', learning_rate: 0.5)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 4, 
+  input_dim: 2, 
+  activation: GRNEXUSActivations::Tanh.new
+))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 1, 
+  input_dim: 4, 
+  activation: GRNEXUSActivations::Sigmoid.new
+))
+
+# Train the model
+model.train(x_train, y_train, epochs: 1000, batch_size: 4)
+
+# Make predictions
+puts model.predict([[0, 0]])  # => ~0.0
+puts model.predict([[1, 1]])  # => ~0.0
+puts model.predict([[0, 1]])  # => ~1.0
+puts model.predict([[1, 0]])  # => ~1.0
+
+# Save model (compatible with Python!)
+model.save('xor_model.nexus')
+```
+
+---
+
+## Deep Learning
+
+### Modern Deep Network with State-of-the-Art Activations
+
+```ruby
+require 'grnexus'
+
+# Create advanced deep network
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  optimizer: 'adam',
+  learning_rate: 0.001,
+  name: 'deep_classifier'
+)
+
+# Layer 1: GELU activation (used in GPT, BERT)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 128,
+  input_dim: 50,
+  activation: GRNEXUSActivations::GELU.new
+))
+model.add(GRNEXUSLayer::BatchNormLayer.new)
+
+# Layer 2: Swish activation (Google's discovery)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 96,
+  input_dim: 128,
+  activation: GRNEXUSActivations::Swish.new
+))
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.3))
+
+# Layer 3: Mish activation (state-of-the-art)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 64,
+  input_dim: 96,
+  activation: GRNEXUSActivations::Mish.new
+))
+model.add(GRNEXUSLayer::BatchNormLayer.new)
+
+# Output layer
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 10,
+  input_dim: 64,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+# View architecture
+model.summary
+
+# Train with intelligent callbacks
+early_stop = GRNEXUSCallbacks::EarlyStopping.new(
+  patience: 10,
+  monitor: 'val_loss'
+)
+
+checkpoint = GRNEXUSCallbacks::ModelCheckpoint.new(
+  filepath: 'best_model.nexus',
+  monitor: 'val_accuracy',
+  save_best_only: true
+)
+
+reduce_lr = GRNEXUSCallbacks::ReduceLROnPlateau.new(
+  monitor: 'val_loss',
+  factor: 0.5,
+  patience: 5
+)
+
+history = model.train(
+  x_train, y_train,
+  epochs: 100,
+  batch_size: 32,
+  validation_data: [x_val, y_val],
+  callbacks: [early_stop, checkpoint, reduce_lr],
+  verbose: true
+)
+
+# Evaluate
+results = model.evaluate(x_test, y_test)
+puts "Test Accuracy: #{results[:accuracy]}%"
+```
+
+### Convolutional Neural Network for Image Classification
+
+```ruby
+require 'grnexus'
+
+# Build CNN for image classification
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  optimizer: 'adam',
+  learning_rate: 0.001,
+  name: 'image_classifier'
+)
+
+# Convolutional layers
+model.add(GRNEXUSLayer::Conv2DLayer.new(
+  filters: 32,
+  kernel_size: 3,
+  input_shape: [28, 28, 1],
+  activation: GRNEXUSActivations::ReLU.new,
+  padding: 'same'
+))
+model.add(GRNEXUSLayer::MaxPoolingLayer.new(pool_size: 2, stride: 2))
+
+model.add(GRNEXUSLayer::Conv2DLayer.new(
+  filters: 64,
+  kernel_size: 3,
+  activation: GRNEXUSActivations::ReLU.new,
+  padding: 'same'
+))
+model.add(GRNEXUSLayer::MaxPoolingLayer.new(pool_size: 2, stride: 2))
+
+# Dense layers
+model.add(GRNEXUSLayer::FlattenLayer.new)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 128,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.5))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 10,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+# Train
+model.train(images, labels, epochs: 50, batch_size: 64)
+model.save('cnn_classifier.nexus')
+```
+
+### LSTM for Sequence Processing
+
+```ruby
+require 'grnexus'
+
+# Build LSTM network
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  optimizer: 'adam',
+  learning_rate: 0.001
+)
+
+# LSTM layers
+model.add(GRNEXUSLayer::LSTMLayer.new(
+  units: 128,
+  return_sequences: true
+))
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.3))
+
+model.add(GRNEXUSLayer::LSTMLayer.new(
+  units: 64,
+  return_sequences: false
+))
+
+# Output
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 10,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+model.train(sequences, labels, epochs: 50, batch_size: 32)
+```
+
+---
+
+## Classical Machine Learning
+
+### K-Nearest Neighbors Classification
+
+```ruby
+require 'grnexus'
+
+# Prepare data
+x_train = [
+  [1.0, 2.0], [1.5, 1.8], [5.0, 8.0],
+  [8.0, 8.0], [1.0, 0.6], [9.0, 11.0]
+]
+y_train = [0, 0, 1, 1, 0, 1]
+
+# Create and train KNN classifier
+knn = GRNEXUSMachineLearning::KNeighborsClassifier.new(n_neighbors: 3)
+knn.fit(x_train, y_train)
+
+# Make predictions
+x_test = [[2.0, 3.0], [7.0, 9.0]]
+predictions = knn.predict(x_test)
+puts "Predictions: #{predictions}"  # => [0, 1]
+
+# Save model
+knn.save('knn_model.lnexus')
+
+# Load model
+loaded_knn = GRNEXUSMachineLearning::KNeighborsClassifier.load('knn_model.lnexus')
+```
+
+### K-Means Clustering
+
+```ruby
+require 'grnexus'
+
+# Prepare data
+data = [
+  [1.0, 2.0], [1.5, 1.8], [5.0, 8.0],
+  [8.0, 8.0], [1.0, 0.6], [9.0, 11.0],
+  [8.0, 2.0], [10.0, 2.0], [9.0, 3.0]
+]
+
+# Create and fit K-Means
+kmeans = GRNEXUSMachineLearning::KMeans.new(n_clusters: 3, max_iter: 300)
+kmeans.fit(data)
+
+# Get cluster assignments
+puts "Labels: #{kmeans.labels}"
+puts "Centroids: #{kmeans.centroids}"
+
+# Predict new data
+new_data = [[2.0, 2.0], [8.0, 9.0]]
+clusters = kmeans.predict(new_data)
+puts "Cluster assignments: #{clusters}"
+
+# Save model
+kmeans.save('kmeans_model.lnexus')
+```
+
+### Linear Regression
+
+```ruby
+require 'grnexus'
+
+# Prepare data
+x_train = [[1.0], [2.0], [3.0], [4.0], [5.0]]
+y_train = [[2.0], [4.0], [6.0], [8.0], [10.0]]
+
+# Create and train linear regression
+lr = GRNEXUSMachineLearning::LinearRegression.new
+lr.fit(x_train, y_train)
+
+# Make predictions
+x_test = [[6.0], [7.0], [8.0]]
+predictions = lr.predict(x_test)
+puts "Predictions: #{predictions}"
+
+# View learned weights
+puts "Weights: #{lr.weights}"
+
+# Save model
+lr.save('linear_regression.lnexus')
+```
+
+### Logistic Regression
+
+```ruby
+require 'grnexus'
+
+# Binary classification data
+x_train = [
+  [1.0, 2.0], [2.0, 3.0], [3.0, 4.0],
+  [6.0, 7.0], [7.0, 8.0], [8.0, 9.0]
+]
+y_train = [[0.0], [0.0], [0.0], [1.0], [1.0], [1.0]]
+
+# Create and train logistic regression
+log_reg = GRNEXUSMachineLearning::LogisticRegression.new(
+  learning_rate: 0.1,
+  max_iter: 1000
+)
+log_reg.fit(x_train, y_train)
+
+# Make predictions
+x_test = [[2.5, 3.5], [7.5, 8.5]]
+predictions = log_reg.predict(x_test)
+puts "Predictions: #{predictions}"  # => [0.0, 1.0]
+
+# Save model
+log_reg.save('logistic_regression.lnexus')
+```
+
+### Naive Bayes Classifier
+
+```ruby
+require 'grnexus'
+
+# Prepare data
+x_train = [
+  [1.0, 2.0], [1.5, 1.8], [5.0, 8.0],
+  [8.0, 8.0], [1.0, 0.6], [9.0, 11.0]
+]
+y_train = [0, 0, 1, 1, 0, 1]
+
+# Create and train Naive Bayes
+nb = GRNEXUSMachineLearning::NaiveBayes.new(n_classes: 2)
+nb.fit(x_train, y_train)
+
+# Make predictions
+x_test = [[2.0, 3.0], [7.0, 9.0]]
+predictions = nb.predict(x_test)
+puts "Predictions: #{predictions}"
+
+# Save model
+nb.save('naive_bayes.lnexus')
+```
+
+---
+
+## Text Processing & NLP
+
+### Sentiment Analysis with TF-IDF
+
+```ruby
+require 'grnexus'
+
+# Training data
+texts = [
+  "I love this product it's excellent",
+  "terrible product very bad quality",
+  "amazing quality exceeded expectations",
+  "worst purchase ever disappointed",
+  "highly recommend great value",
+  "waste of money poor quality"
+]
+labels = [[1, 0], [0, 1], [1, 0], [0, 1], [1, 0], [0, 1]]
+
+# Create vocabulary and vectorize
+vocab = GRNexusTextProcessing::Vocabulary.new(
+  texts,
+  max_vocab_size: 100,
+  min_frequency: 1
+)
+
+vectorizer = GRNexusTextProcessing::TextVectorizer.new(vocab)
+x_train = texts.map { |text| vectorizer.vectorize(text) }
+
+# Build sentiment analyzer
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  learning_rate: 0.05,
+  name: 'sentiment_analyzer'
+)
+
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 32,
+  input_dim: vocab.size,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.3))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 16,
+  input_dim: 32,
+  activation: GRNEXUSActivations::Tanh.new
+))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 2,
+  input_dim: 16,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+# Train
+model.train(x_train, labels, epochs: 100, batch_size: 2, verbose: true)
+
+# Test predictions
+test_text = "excellent product very good"
+test_vector = vectorizer.vectorize(test_text)
+prediction = model.predict([test_vector])[0]
+sentiment = prediction[0] > prediction[1] ? "POSITIVE" : "NEGATIVE"
+confidence = prediction.max * 100
+
+puts "Text: '#{test_text}'"
+puts "Sentiment: #{sentiment} (#{confidence.round(2)}% confidence)"
+
+# Save for cross-language use
+model.save('sentiment_analyzer.nexus')
+```
+
+
+### Advanced Sentiment Analysis with Word Embeddings
+
+```ruby
+require 'grnexus'
+
+# Larger dataset
+texts = [
+  "This movie is absolutely fantastic and amazing",
+  "Terrible film waste of time and money",
+  "Great acting superb storyline loved it",
+  "Boring predictable disappointing experience",
+  "Outstanding performance brilliant direction",
+  "Awful terrible waste of time"
+]
+labels = [[1, 0], [0, 1], [1, 0], [0, 1], [1, 0], [0, 1]]
+
+# Create vocabulary
+vocab = GRNexusTextProcessing::Vocabulary.new(texts, max_vocab_size: 5000)
+
+# Normalize texts to sequences of indices
+max_length = 20
+x_train = texts.map { |text| vocab.normalize_text(text, max_length: max_length) }
+
+# Build model with embedding layer
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  learning_rate: 0.001,
+  name: 'sentiment_embeddings'
+)
+
+# Embedding layer converts word indices to dense vectors
+model.add(GRNEXUSLayer::EmbeddingLayer.new(
+  vocab_size: vocab.size,
+  embedding_dim: 128,
+  input_length: max_length
+))
+
+# Flatten embeddings
+model.add(GRNEXUSLayer::FlattenLayer.new)
+
+# Dense layers
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 64,
+  input_dim: max_length * 128,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.5))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 32,
+  input_dim: 64,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 2,
+  input_dim: 32,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+# Train
+model.train(x_train, labels, epochs: 50, batch_size: 16, verbose: true)
+
+# Predict
+test_text = "amazing movie highly recommended"
+test_seq = vocab.normalize_text(test_text, max_length: max_length)
+prediction = model.predict([test_seq])[0]
+sentiment = prediction[0] > prediction[1] ? "POSITIVE" : "NEGATIVE"
+confidence = prediction.max * 100
+
+puts "Sentiment: #{sentiment} (#{confidence.round(2)}% confidence)"
+
+model.save('sentiment_embeddings.nexus')
+```
+
+### Text Vectorization and TF-IDF
+
+```ruby
+require 'grnexus'
+
+# Document corpus
+documents = [
+  "Ruby is a dynamic programming language",
+  "Python is popular for machine learning",
+  "Machine learning requires data processing",
+  "Ruby has elegant syntax and powerful features"
+]
+
+# Create TF-IDF vectorizer
+tfidf = GRNexusTextProcessing::TFIDFVectorizer.new(documents)
+
+# Vectorize new document
+new_doc = "Ruby programming is elegant"
+vector = tfidf.vectorize(new_doc)
+puts "TF-IDF Vector: #{vector}"
+
+# Calculate document similarity
+similarity = tfidf.similarity(documents[0], documents[3])
+puts "Similarity: #{similarity}"
+```
+
+---
+
+## Numeric Processing
+
+### Statistical Analysis
+
+```ruby
+require 'grnexus'
+
+data = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+
+# Basic statistics
+mean = GRNEXUSNumericProcessing.mean(data)
+std = GRNEXUSNumericProcessing.std(data)
+variance = GRNEXUSNumericProcessing.variance(data)
+median = GRNEXUSNumericProcessing.median(data)
+
+puts "Mean: #{mean}"
+puts "Std Dev: #{std}"
+puts "Variance: #{variance}"
+puts "Median: #{median}"
+
+# Correlation
+x = [1.0, 2.0, 3.0, 4.0, 5.0]
+y = [2.0, 4.0, 6.0, 8.0, 10.0]
+correlation = GRNEXUSNumericProcessing.correlation(x, y)
+puts "Correlation: #{correlation}"
+```
+
+### Data Normalization
+
+```ruby
+require 'grnexus'
+
+data = [1.0, 2.0, 3.0, 4.0, 5.0, 10.0, 15.0, 20.0]
+
+# Z-Score normalization
+zscore = GRNEXUSNumericProcessing::ZScoreNormalize.new
+normalized = zscore.process(data)
+puts "Z-Score Normalized: #{normalized}"
+
+# Min-Max normalization
+minmax = GRNEXUSNumericProcessing::MinMaxNormalize.new(min: 0, max: 1)
+scaled = minmax.process(data)
+puts "Min-Max Scaled: #{scaled}"
+
+# L2 normalization
+l2_norm = GRNEXUSNumericProcessing::L2Normalize.new
+l2_normalized = l2_norm.process(data)
+puts "L2 Normalized: #{l2_normalized}"
+```
+
+### Time Series Processing
+
+```ruby
+require 'grnexus'
+
+# Generate time series data
+time_series = (0..199).map { |i| Math.sin(i * 0.05) * 10 + rand * 2 }
+
+# Moving average smoothing
+ma = GRNEXUSNumericProcessing::MovingAverage.new(window_size: 5)
+smoothed = ma.process(time_series)
+
+# Calculate differences
+diff = GRNEXUSNumericProcessing.difference(time_series)
+
+# Integration
+integrated = GRNEXUSNumericProcessing.integrate(diff)
+
+puts "Original length: #{time_series.length}"
+puts "Smoothed length: #{smoothed.length}"
+puts "Differences length: #{diff.length}"
+```
+
+### Time Series Forecasting
+
+```ruby
+require 'grnexus'
+
+# Generate and preprocess time series
+time_series = (0..199).map { |i| Math.sin(i * 0.05) * 10 + rand * 2 }
+
+# Smooth and normalize
+ma = GRNEXUSNumericProcessing::MovingAverage.new(window_size: 5)
+smoothed = ma.process(time_series)
+
+zscore = GRNEXUSNumericProcessing::ZScoreNormalize.new
+normalized = zscore.process(smoothed)
+
+# Create sliding windows
+window_size = 10
+x_train = []
+y_train = []
+
+(0...(normalized.length - window_size - 1)).each do |i|
+  x_train << normalized[i, window_size]
+  y_train << [normalized[i + window_size]]
+end
+
+# Build forecasting model
+model = GRNexus::NeuralNetwork.new(loss: 'mse', learning_rate: 0.01)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 64,
+  input_dim: window_size,
+  activation: GRNEXUSActivations::Tanh.new
+))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 32,
+  input_dim: 64,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::DenseLayer.new(units: 1, input_dim: 32))
+
+# Train
+model.train(x_train, y_train, epochs: 50, batch_size: 16, verbose: true)
+
+# Forecast next value
+future_window = normalized[-window_size..-1]
+prediction = model.predict([future_window])[0]
+puts "Next value prediction: #{prediction[0].round(4)}"
+
+model.save('time_series_forecaster.nexus')
+```
+
+---
+
+## Advanced Features
+
+### Cross-Language Model Compatibility
+
+Train in Ruby, deploy in Python (or vice versa):
+
+```ruby
+# Train in Ruby
+model = GRNexus::NeuralNetwork.new(
+  loss: 'cross_entropy',
+  learning_rate: 0.1,
+  name: 'shared_model'
+)
+
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 128,
+  input_dim: 50,
+  activation: GRNEXUSActivations::GELU.new
+))
+model.add(GRNEXUSLayer::BatchNormLayer.new)
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 10,
+  input_dim: 128,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+model.train(x_train, y_train, epochs: 50)
+model.save('shared_model.nexus')
+```
+
+Then in Python:
+
+```python
+from grnexus import NeuralNetwork
+
+# Load Ruby-trained model
+model = NeuralNetwork.load('shared_model.nexus')
+# => Loading model: GRNexus v2.0 (created in Ruby)
+
+# Continue training or make predictions
+predictions = model.predict(test_data)
+```
+
+### Model Inspection Without Loading
+
+```ruby
+require 'grnexus'
+
+# Inspect model metadata without loading it
+GRNexus::NeuralNetwork.inspect_model('my_model.nexus')
+
+# Output:
+# ================================================================================
+# MODEL INSPECTION: my_model.nexus
+# ================================================================================
+# Framework: GRNexus
+# Version: 2.0
+# Language: Ruby
+# Name: sentiment_analyzer
+# Created: 2024-01-15T10:30:00Z
+# Loss Function: cross_entropy
+# Optimizer: adam
+# Learning Rate: 0.001
+#
+# Metadata:
+#   Total Parameters: 6,538
+#   Trainable Parameters: 6,538
+#   Layers Count: 5
+#
+# Architecture:
+#   Layer 1: DenseLayer
+#     Units: 128
+#     Activation: ReLU
+#     Trainable: true
+#   Layer 2: BatchNormLayer
+#     Trainable: true
+#   ...
+```
+
+### Model Architecture Summary
+
+```ruby
+require 'grnexus'
+
+model = GRNexus::NeuralNetwork.new(name: 'example_model')
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 128,
+  input_dim: 50,
+  activation: GRNEXUSActivations::ReLU.new
+))
+model.add(GRNEXUSLayer::BatchNormLayer.new)
+model.add(GRNEXUSLayer::DropoutLayer.new(rate: 0.3))
+model.add(GRNEXUSLayer::DenseLayer.new(
+  units: 10,
+  input_dim: 128,
+  activation: GRNEXUSNormalization::Softmax.new
+))
+
+# Display architecture
+model.summary
+
+# Output:
+# ================================================================================
+# Model: example_model
+# ================================================================================
+#                     Output Shape          Param #
+# --------------------------------------------------------------------------------
+# DenseLayer (ReLU) (1)         (None, 128)              6528
+# BatchNormLayer (2)            (None, 128)              2
+# DropoutLayer (3)              (None, 128)              0
+# DenseLayer (Softmax) (4)      (None, 10)               1290
+# ================================================================================
+# Total params: 7,820
+# Trainable params: 7,820
+# Non-trainable params: 0
+# ================================================================================
+```
+
+### Training History Visualization
+
+```ruby
+require 'grnexus'
+
+# Train model
+history = model.train(
+  x_train, y_train,
+  epochs: 50,
+  batch_size: 32,
+  validation_data: [x_val, y_val],
+  verbose: true
+)
+
+# Plot training history (text-based)
+model.plot_history(metrics: ['loss', 'accuracy', 'val_loss', 'val_accuracy'])
+
+# Access history data
+puts "Final training loss: #{history[:loss].last}"
+puts "Final validation accuracy: #{history[:val_accuracy].last}"
+puts "Best validation loss: #{history[:val_loss].min}"
+```
+
+### Custom Learning Rate Schedules
+
+```ruby
+require 'grnexus'
+
+# Exponential decay
+lr_scheduler = GRNEXUSCallbacks::LearningRateScheduler.new do |epoch|
+  initial_lr = 0.1
+  decay_rate = 0.95
+  initial_lr * (decay_rate ** epoch)
+end
+
+# Step decay
+step_scheduler = GRNEXUSCallbacks::LearningRateScheduler.new do |epoch|
+  initial_lr = 0.1
+  drop_every = 10
+  initial_lr * (0.5 ** (epoch / drop_every))
+end
+
+# Use in training
+model.train(
+  x_train, y_train,
+  epochs: 100,
+  callbacks: [lr_scheduler]
+)
+```
+
+---
+
+## API Reference
+
+### Neural Network Layers
+
+**DenseLayer** - Fully connected layer
+```ruby
+GRNEXUSLayer::DenseLayer.new(
+  units: 128,
+  input_dim: 50,
+  activation: GRNEXUSActivations::ReLU.new
+)
+```
+
+**Conv2DLayer** - 2D Convolutional layer
+```ruby
+GRNEXUSLayer::Conv2DLayer.new(
+  filters: 32,
+  kernel_size: 3,
+  input_shape: [28, 28, 1],
+  activation: GRNEXUSActivations::ReLU.new,
+  padding: 'same'
+)
+```
+
+**LSTMLayer** - Long Short-Term Memory
+```ruby
+GRNEXUSLayer::LSTMLayer.new(
+  units: 128,
+  return_sequences: true
+)
+```
+
+**GRULayer** - Gated Recurrent Unit
+```ruby
+GRNEXUSLayer::GRULayer.new(
+  units: 64,
+  return_sequences: false
+)
+```
+
+**EmbeddingLayer** - Word embeddings
+```ruby
+GRNEXUSLayer::EmbeddingLayer.new(
+  vocab_size: 10000,
+  embedding_dim: 300,
+  input_length: 100
+)
+```
+
+**BatchNormLayer** - Batch normalization
+```ruby
+GRNEXUSLayer::BatchNormLayer.new(
+  epsilon: 1e-5,
+  momentum: 0.1
+)
+```
+
+**DropoutLayer** - Regularization
+```ruby
+GRNEXUSLayer::DropoutLayer.new(rate: 0.5)
+```
+
+### Activation Functions
+
+**Modern Activations**
+- `GRNEXUSActivations::GELU.new` - Gaussian Error Linear Unit (GPT, BERT)
+- `GRNEXUSActivations::Swish.new` - Self-gated activation (Google)
+- `GRNEXUSActivations::Mish.new` - State-of-the-art smooth activation
+- `GRNEXUSActivations::Snake.new` - Periodic activation
+
+**Classic Activations**
+- `GRNEXUSActivations::ReLU.new` - Rectified Linear Unit
+- `GRNEXUSActivations::LeakyReLU.new` - Leaky ReLU
+- `GRNEXUSActivations::ELU.new` - Exponential Linear Unit
+- `GRNEXUSActivations::SELU.new` - Scaled ELU
+- `GRNEXUSActivations::Sigmoid.new` - Sigmoid
+- `GRNEXUSActivations::Tanh.new` - Hyperbolic tangent
+
+**Normalization**
+- `GRNEXUSNormalization::Softmax.new` - Softmax
+- `GRNEXUSNormalization::LogSoftmax.new` - Log Softmax
+- `GRNEXUSNormalization::LayerNorm.new` - Layer normalization
+
+### Training Callbacks
+
+**EarlyStopping** - Stop training when metric stops improving
+```ruby
+GRNEXUSCallbacks::EarlyStopping.new(
+  monitor: 'val_loss',
+  patience: 10,
+  min_delta: 0.001,
+  mode: 'min'
+)
+```
+
+**ModelCheckpoint** - Save best model during training
+```ruby
+GRNEXUSCallbacks::ModelCheckpoint.new(
+  filepath: 'best_model.nexus',
+  monitor: 'val_accuracy',
+  save_best_only: true,
+  mode: 'max'
+)
+```
+
+**ReduceLROnPlateau** - Reduce learning rate when metric plateaus
+```ruby
+GRNEXUSCallbacks::ReduceLROnPlateau.new(
+  monitor: 'val_loss',
+  factor: 0.5,
+  patience: 5,
+  min_lr: 0.00001
+)
+```
+
+**LearningRateScheduler** - Custom learning rate schedule
+```ruby
+GRNEXUSCallbacks::LearningRateScheduler.new do |epoch|
+  0.1 * (0.95 ** epoch)
+end
+```
+
+### Classical ML Algorithms
+
+**K-Nearest Neighbors**
+```ruby
+knn = GRNEXUSMachineLearning::KNeighborsClassifier.new(n_neighbors: 5)
+knn.fit(x_train, y_train)
+predictions = knn.predict(x_test)
+```
+
+**K-Means Clustering**
+```ruby
+kmeans = GRNEXUSMachineLearning::KMeans.new(n_clusters: 3, max_iter: 300)
+kmeans.fit(data)
+clusters = kmeans.predict(new_data)
+```
+
+**Linear Regression**
+```ruby
+lr = GRNEXUSMachineLearning::LinearRegression.new
+lr.fit(x_train, y_train)
+predictions = lr.predict(x_test)
+```
+
+**Logistic Regression**
+```ruby
+log_reg = GRNEXUSMachineLearning::LogisticRegression.new(
+  learning_rate: 0.1,
+  max_iter: 1000
+)
+log_reg.fit(x_train, y_train)
+predictions = log_reg.predict(x_test)
+```
+
+**Naive Bayes**
+```ruby
+nb = GRNEXUSMachineLearning::NaiveBayes.new(n_classes: 2)
+nb.fit(x_train, y_train)
+predictions = nb.predict(x_test)
+```
+
+---
+
+## Documentation
+
+### Complete Documentation
+Full documentation and advanced examples: [GitHub Repository](https://github.com/grcodedigitalsolutions/GRNexus)
+
+### File Formats
+- **`.nexus`** - Neural network models (cross-language compatible)
+- **`.lnexus`** - Classical ML models (KNN, K-Means, Linear/Logistic Regression, Naive Bayes)
+
+### Platform Support
+- **Windows**: Pre-compiled DLL files included
+- **macOS**: Pre-compiled dylib files included
+- **Linux**: Pre-compiled SO files included
+
+### Requirements
+- Ruby >= 3.0.0
+- FFI gem (automatically installed)
+- JSON gem (automatically installed)
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at:
+https://github.com/grcodedigitalsolutions/GRNexus
+
+---
+
+## License
+
+This gem is available as open source under the terms of the [GPL-3.0 License](LICENSE).
+
+Copyright (C) 2024 GR Code Digital Solutions
+
+---
+
+## Author
+
+**GR Code Digital Solutions**
+
+Email: gr.code.studio@gmail.com
+
+GitHub: [@grcodedigitalsolutions](https://github.com/grcodedigitalsolutions)
+
+---
+
+**Made with passion for the Ruby community**