micrograd-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f4ecdb2b1d0efa6a960a3a5006c4d26658bb2fbabc3f491eb4e23a4cdcc77b8
+  data.tar.gz: 90b64a0ccf554b5b28c1935230b5c7aa92248b898c81566cad5a59effaf75532
+SHA512:
+  metadata.gz: 2eb06299d644f414fc295a330314814cdd3a38f50a95ea3d3c2a53789dfe3672e676b46653c49389d691d04ab971d6167c0ecc486eaf0717ecfba77f8306e442
+  data.tar.gz: d5250318f2381e09f24cab75b25b00526cabc3e419f9b31199dc3275d0731327f44d3d0ad7e2b8244a47790042d22fa4bd537e172fb2f6aef2c8c449abd50bb0

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,11 @@
+inherit_from:
+  - "https://raw.githubusercontent.com/joeldrapper/goodcop/refs/heads/main/base.yml"
+
+AllCops:
+  TargetRubyVersion: 3.4
+
+Lint/UnderscorePrefixedVariableName:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Guardfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+guard :shell do
+  watch(%r{^lib/micrograd/.*\.rb$}) do |m|
+    puts "File #{m[0]} changed, regenerating d2 graph..."
+    system("bundle exec ruby lib/micrograd/examples.rb")
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Sean Collins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# Micrograd-rb 🧮💎📉
+
+This is an example implementation of a **small neural network library** in Ruby, with [automatic differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation) and [backpropagation](https://en.wikipedia.org/wiki/Backpropagation). If you have no clue what that means, check out [this video series](https://www.youtube.com/watch?v=aircAruvnKk&list=PLZHQObOWTQDNU6R1_67000Dx_ZCJB-3pi), which explains Neural Networks and Deep Learning visually.
+
+I implemented this library by going through the YouTube lecture
+[“The spelled-out intro to neural networks and backpropagation: building micrograd”](https://www.youtube.com/watch?v=VMj-3S1tku0&list=PLAqhIrjkxbuWI23v9cThsA9GvCAUhRvKZ)
+by Andrej Karpathy.
+It's the first in a series called "Neural Networks: From Zero to Hero",
+which builds up from the basic building blocks all the way to implementing GPT-2.
+As I watched the video, I translated the Python code into Ruby.
+
+There's a canonical implementation of the functionality implemented in Python, available at [karpathy/micrograd](https://github.com/karpathy/micrograd).
+I didn't reference the Python micrograd codebase at all,
+nor any of the other micrograd implementations [in Ruby](https://github.com/search?utf8=%E2%9C%93&q=micrograd+language%3ARuby+&type=repositories),
+nor in any other languages.
+
+This codebase could be helpful if you know about how Neural Networks work in general,
+and you're interested in seeing how to implement a simple one in Ruby.
+
+If you're building anything real, you probably want to use [torch.rb](https://github.com/ankane/torch.rb), which is based on libtorch, the high-performance C++ library that powers PyTorch.
+
+### Motivation
+Why? Because I am learning neural networks & deep learning.
+I know enough Python to have been able to write it in Python,
+but (1) I didn't want to just write all the same code he wrote and (2) I learn best by adapting principles to a different language and taking a different approach.
+I know Ruby best (and enjoy writing it the most), so it was the obvious choice.
+
+## Approach
+I implemented it in **idiomatic** Ruby: I didn't just copy the Python and adapt the syntax directly:
+* I used bang methods, e.g. `Value#backward!` (instead of just `#backward`), since in Ruby we use that to signify that we're mutating the object in-place.
+* I used methods on Enumerable instead of using loops (especially since we don't have list comprehension in Ruby)
+* I expanded short variable/parameter names to be unabbreviated in most cases
+* I used symbol keys
+* I used keyword args in most cases
+* I extracted `Visualizer` and `TopoGraph` classes, instead of encapsulating that logic within `Value`.
+
+And, since it's Ruby, I also implemented it in an **idiosyncratic** way, in a style I personally prefer:
+* I added a bracket constructor (factory) syntax (e.g. `Micrograd::Value[scalar_value]`), since I was jealous of Python's terseness with no `.new` when creating Value objects.
+  * I also added a shorthand to pair labels with scalar data values via this syntax: `Micrograd::Value[label: scalar_value]`.
+  * I think using parens, e.g. `Micrograd::Value(...)` to construct the value would work too (since that's the convention for conversion methods).
+* Prefer immutability by default, when realistic. Mutating state is hard to reason about, avoiding it as much as possible is preferable.
+* Prefer using `attr_reader` internally for accessing instance variables (so all references to instance variables are mutation. This makes it easier to find them).
+* Prefer injecting dependencies rather than relying on global state. You can see I did this with `random:` being passed into `Neuron`, `Layer`, `MLP`, and `Training`.
+
+I balanced that with being **pragmatic**:
+* In `lib/micrograd/value.rb`, I do use mutation of instance variables to update `@grad` and `@data`. In many (most?) applications, immutability can provide better performance since it's easier on the Garbage Collector. However, these kind of neural nets are meant to be computed at a massive scale and repeatedly, on GPU's. In that case, creating millions or billions of objects on each iteration would obviously be much slower than mutating in place, since object creation is relatively slow and memory-intensive.
+* In `lib/micrograd/value.rb`, I used `self.` when it's not necessary (and disabled the `Style/RedundantSelf` to allow this). Why? Because many of the methods are operations that reference `other`, so I find it more readable to have symmetry between `self` and `other`. And, for the rest of the class, I wanted to be consistent with that choice. This is also the standard way to access instance variables in Python.
+* I used `Enumerable#reduce` which is an alias for `Enumerable#inject`. I typically default to using `#inject` but figured non-Rubyists might read this codebase, and `#reduce` is the name that's more common in other languages, so I think it makes more sense here.
+* I kept the leading underscore for `_backward` lambda, to signify it's different from the externally facing `backward!`. I could have named it `backward` (without the bang), but I feel like the underscore reveals the intent that it's an implementation detail and shouldn't be used directly. This is a pattern used occasionally in Ruby, and I think it's worth using here.
+
+I **extended** the work from the video slightly. At the end, he builds out the training process using the MLP (multi-level perceptron), ad-hoc in the Jupyter notebook. I did that as well first, in the `MLP` class's spec file. After that, though, I extracted an `Micrograd::Training` class to encapsulate and generalize that work (and tested it separately).
+
+
+## Overview of library
+
+#### Value
+The basic object is the `Micrograd::Value`. This has a `data` attribute (which is the underlying scalar value), a `grad` attribute, and a `backward!` method. I wanted to follow the convention established by micrograd (and PyTorch), but I think I would have named this class `Node` and have the `data` attribute be named `value` or `scalar` instead. While we're at it, I'd also name `grad` as `gradient`, but that's an even starker break from convention.
+
+This class handles:
+- unary operations
+- binary operations, with `other` Values,
+- computing `grad`,
+- starting the `backward!` pass,
+- a `gradient_step!` method, which is used in the `Training` class, in order to keep all mutation within its own class
+
+The `backward!` method uses a helper class called `TopoSort`
+
+It also has a convenience method `generate_image`, which uses the `Visualizer` class to generate a visual representation of the network (with [d2](https://github.com/terrastruct/d2)).
+
+#### Building up a neural net (using `Neuron`, `Layer`, `MLP`, and `Training`)
+
+The rest of the classes all stack on top of each other to build a small-scale [feedforward neural net](feedforward neural net)[https://en.wikipedia.org/wiki/Feedforward_neural_network].
+
+The basic building block here is the `Neuron`. This uses `Value` for its *weights* and *bias*.
+
+Those are combined into a `Layer`, which is then combined into an `MLP` ([multi-layer perceptron](https://en.wikipedia.org/wiki/Multilayer_perceptron)). Again, I'd usually name this class its full name but MLP is a ubiquitous acronym in Deep Learning, and I didn't want to buck the conventions too much.
+
+These three classes (`Neuron`, `Layer`, and `MLP`) are all quite small.
+
+Finally, there is the `Training` class. This is used to train the neural net! This is the real guts of the library, the fullest expression of what we're trying to accomplish.
+
+The objective is to take many training inputs, a set of targets (desired outputs) for each output and get an `MLP` object that's trained to map *any* values (even ones we didn't train with) to a set of outputs, based on what it learned from the example inputs and targets. We also have to tell it how large we want the neural net to be.
+
+So, this takes:
+1. how many layers and what size you want as an array, e.g. [3, 2, 2, 2, 2, 1] signifies: 3 input scalars, 4 'hidden' internal layers of 2 neurons each, and 1 output value.
+2. an array of arrays of `inputs` values
+3. an array of `target` values (for each of the inputs)
+4. an optional `Random` instance (else it just defaults to `Random.new`, helpful for reproducing results and testing)
+
+Then once it's created, the training occurs when `call` is received.
+This takes:
+1. number of `epochs` (how many times the gradient descent occurs)
+2. the `learning_rate` (how much we tweak the parameters for each epoch)
+3. an optional `verbose` flag if you want the loss function results to be printed as it goes. This is helpful for manually adjusting the number of `epochs` and the `learning_rate`
+
+What this does is:
+1. First `iterate!` on the MLP, by:
+  1. calculating the forward pass,
+  2. calculate the loss (using difference of two squares)
+  3. run `backward!` on the loss
+
+2. Then `epoch` number of times, do the following:
+  1. Descend!! That is: go through all the parameters in the MLP and step them downward a small amount (the `learning_rate`)
+  2. Recalculate the loss, but `iterate!`ing the same way as above
+
+3. Once that is done, return a `Training::Result` object, which holds the last run's `outputs` and the `mlp`. This `MLP` is now the trained neural net.
+
+4. [????](https://youtu.be/2B3slX6-_20?feature=shared&t=6)
+
+5. Profit!
+
+## Coding modalities
+In the lecture, Andrej uses a Jupyter notebook: these are ubiquitous in Python Data/AI/ML world.
+There's a library called `iruby` that let you use Ruby in Jupyter notebooks, but I didn't do that.
+
+> As an aside, I found it extremely hard to reason about state in Jupyter when watching the videos.
+> I guess it may be easier when you're coding in a notebook yourself, since your memory is more clear,
+> but having blocks of code that redefine variables executed ad-hoc in different sequences... Ah!! GOTO considered harmful, indeed!
+
+I preferred to write code in classes, then execute it in a file when necessary (e.g. `ruby lib/micrograd/examples.rb`).
+Sometimes I used `bin/console` to load the files and work with them like that, in an `irb` session.
+
+Finally, I transitioned to using RSpec to ensure behavior stayed consistent as I refactored.
+That made it much easier to work with.
+
+## TODO's
+- [ ] Push to Rubygems.org
+- [ ] Fix CI
+- [ ] Explain Value#backward! and updating grad
+- [ ] Convert examples.rb to runnable script in `bin/`
+- [ ] Update README with actual usages instead of telling people to look at the specs
+- [ ] Adapt/complete the [exercises](https://colab.research.google.com/drive/1FPTx1RXtBfc4MaTkf7viZZD4U2F9gtKN?usp=sharing) from the video description
+
+
+## COULD-DO's (but probably will not)
+- [ ] Add alternate `Training` runner that gets the loss function within the threshold, and reports the number of steps
+- [ ] Adapt Torch examples from video with torch.rb
+- [ ] Add a `Micrograd::Torch::` namespace that implements the same API as Micrograd (`Value`, `Neuron`, `Layer`, `MLP`, `Training`), using torch.rb
+- [ ] Fix `# TODO` in `Training` class (validate and/or compute sizes)
+
+
+## Installation
+You're probably just curious and may read the code and specs here on GitHub.
+But if you want to mess around with the code, you can clone this repo.
+
+I don't see why you'd want to install this as a dependency, but you could do `gem "micrograd", github: "cllns/micrograd"` if you want.
+
+## Usage
+Take a look at the specs, particularly `specs/training_spec.rb`, for the highest level. Or start at `specs/value_spec.rb` and work your way up the stack. There's also a `lib/micrograd/examples.rb` which be be run directly with `ruby lib/micrograd/examples.rb`.
+
+## Contributing
+No need. This was an educational exercise. :)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/micrograd/examples.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "value"
+require_relative "visualizer"
+
+module Micrograd
+  class Examples
+    def initialize
+      x1 = Value[x1: 2]
+      x2 = Value[x2: 0]
+      w1 = Value[w1: -3]
+      w2 = Value[w2: 1]
+      b = Value[b: 6.8813735870195432]
+
+      x1w1 = (x1 * w1).with_label(:x1w1)
+      x2w2 = (x2 * w2).with_label(:x2w2)
+
+      x1w1x2w2 = (x1w1 + x2w2).with_label(:x1w1x2w2)
+      n = (x1w1x2w2 + b).with_label(:n)
+
+      # o = n.tanh.with_label(:o)
+      # Or, the equivalent implemented from our operations:
+      e = (2 * n).exp
+      o = (e - 1) / (e + 1)
+
+      o.backward!
+
+      @node = o
+    end
+
+    def call
+      puts "generating image of graph"
+      Visualizer.new(@node).generate_image
+    end
+
+    # First version had initializer with:
+    #  a = Value[a: 2]
+    #  b = Value[b: -3]
+    #  c = Value[c: 10]
+    #  e = (a * b).with_label(:e)
+    #  d = (e + c).with_label(:d)
+    #  f = Value[f: -2]
+    #  loss = (d * f).with_label(:L)
+    #  @node = loss
+  end
+end
+
+Micrograd::Examples.new.call

data/lib/micrograd/layer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "neuron"
+
+module Micrograd
+  class Layer
+    attr_reader :neurons
+
+    def initialize(n_in, n_out, random: Random.new)
+      @neurons = n_out.times.map { Neuron.new(n_in, random:) }
+    end
+
+    def call(x)
+      outs = neurons.map { |neuron| neuron.call(x) }
+      if outs.length == 1
+        outs.first
+      else
+        outs
+      end
+    end
+
+    def parameters
+      neurons.flat_map(&:parameters)
+    end
+  end
+end

data/lib/micrograd/mlp.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "layer"
+
+module Micrograd
+  class MLP
+    attr_reader :layers
+
+    def initialize(n_in, n_outs, random: Random.new)
+      size = [n_in] + n_outs
+      @layers = n_outs.length.times.map do |i|
+        Layer.new(size[i], size[i + 1], random:)
+      end
+    end
+
+    def call(input)
+      layers.reduce(input) { |input, layer| layer.call(input) }
+    end
+
+    def parameters
+      layers.flat_map(&:parameters)
+    end
+
+    def zero_grad!
+      parameters.each(&:zero_grad!)
+    end
+  end
+end

data/lib/micrograd/neuron.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "value"
+
+module Micrograd
+  class Neuron
+    attr_reader :weights, :bias
+
+    def initialize(n_in, random: Random.new)
+      @weights = n_in.times.map { Value[random.rand(-1.0..1)] }
+      @bias = Value[random.rand(-1.0..1)]
+    end
+
+    def call(inputs)
+      act = weights.zip(inputs).map { |weight, input| weight * input }.sum + bias
+      act.tanh
+    end
+
+    def parameters
+      weights + [bias]
+    end
+  end
+end

data/lib/micrograd/topo_sort.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Micrograd
+  class TopoSort
+    def initialize(start_node)
+      @start_node = start_node
+    end
+
+    def call
+      build(node: @start_node)
+    end
+
+    private
+
+    def build(node:, topo: [], visited: [])
+      unless visited.include?(node)
+        visited << node
+
+        node.previous.each do |child|
+          build(node: child, topo:, visited:)
+        end
+
+        topo << node
+      end
+    end
+  end
+end

data/lib/micrograd/training.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "mlp"
+
+module Micrograd
+  class Training
+    attr_reader :mlp, :inputs, :targets
+
+    Result = Data.define(:mlp, :outputs)
+
+    def initialize(layer_sizes:, inputs:, targets:, random: Random.new)
+      n_in, *n_outs = layer_sizes
+      # TODO: Ensure n_in == inputs.length, n_outs == targets.length
+      @mlp = MLP.new(n_in, n_outs, random:)
+      @inputs = inputs
+      @targets = targets
+    end
+
+    def call(epochs:, learning_rate:, verbose: false)
+      # Assign the last iterate! result to outputs
+      outputs = epochs.times.reduce(nil) do |_, i|
+        # Skip the first pass because it's the initialization
+        gradient_descent!(learning_rate) unless i == 0
+
+        iterate!((i if verbose))
+      end
+
+      print_summary(outputs) if verbose
+
+      Result.new(mlp:, outputs: outputs.map(&:data))
+    end
+
+    private
+
+    def iterate!(i)
+      outputs = forward_pass
+      loss = calculate_loss(outputs)
+      loss.backward!
+      puts "#{i}: #{loss.data}" if i
+      outputs
+    end
+
+    def gradient_descent!(learning_rate)
+      mlp.parameters.each do |parameter|
+        parameter.gradient_step!(learning_rate)
+      end
+    end
+
+    def forward_pass
+      mlp.zero_grad!
+      inputs.map { |input| mlp.call(input) }
+    end
+
+    def calculate_loss(outputs)
+      # Difference of two squares
+      targets.zip(outputs).map do |target, output|
+        (output - target) ** 2
+      end.sum
+    end
+
+    def print_summary(outputs)
+      puts "Final loss: #{calculate_loss(outputs).data}"
+      puts "Targets: #{targets}"
+      print "Outputs: "
+    end
+  end
+end

data/lib/micrograd/value.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "topo_sort"
+require_relative "visualizer"
+
+module Micrograd
+  class Value
+    attr_reader :data, :label, :grad, :operation, :previous
+
+    protected attr_reader :_backward
+
+    def initialize(data:, label: nil, operation: nil, previous: [], _backward: -> (_) {})
+      @data = data
+      @label = label
+      @operation = operation
+      @previous = previous.to_set
+      @_backward = _backward
+
+      @grad = nil
+    end
+
+    def self.[](*args, **kwargs)
+      if args.size == 1
+        label = nil
+        data = args.first
+      elsif kwargs.size == 1
+        label, data = kwargs.first
+      else
+        raise ArgumentError.new("Provide data or label: data as arg")
+      end
+      new(label:, data:)
+    end
+
+    def id
+      self.object_id
+    end
+
+    def inspect
+      label = self.label.nil? ? "" : ", label: #{self.label.inspect}"
+      "Value[data: #{data}#{label}]"
+    end
+
+    def +(other)
+      unless other.is_a?(Value)
+        other = Value[scalar: other]
+      end
+
+      Value.new(
+        data: self.data + other.data,
+        operation: :+,
+        previous: [self, other],
+        _backward: lambda do |value|
+          self.add_grad!(value.grad)
+          other.add_grad!(value.grad)
+        end
+      )
+    end
+
+    def -(other)
+      self + (-other)
+    end
+
+    def -@
+      self * -1
+    end
+
+    def *(other)
+      unless other.is_a?(Value)
+        other = Value[scalar: other]
+      end
+
+      Value.new(
+        data: self.data * other.data,
+        operation: :*,
+        previous: [self, other],
+        _backward: lambda do |value|
+          self.add_grad!(other.data * value.grad)
+          other.add_grad!(self.data * value.grad)
+        end
+      )
+    end
+
+    def /(other)
+      self * (other ** -1)
+    end
+
+    def **(pow)
+      unless pow.is_a?(Numeric)
+        raise TypeError.new("Cannot raise #{pow.class} to a power")
+      end
+
+      Value.new(
+        data: self.data ** pow,
+        label: :"**#{pow}",
+        operation: :**,
+        previous: [self],
+        _backward: lambda do |value|
+          self.add_grad!(value.grad * pow * (self.data ** (pow - 1)))
+        end
+      )
+    end
+
+    def tanh
+      t = (Math.exp(2 * self.data) - 1) / (Math.exp(2 * self.data) + 1)
+      # Other valid options
+      # Math.tanh(self.data)
+      # (Math.exp(self.data) - Math.exp(-self.data)) / (Math.exp(self.data) + Math.exp(-self.data))
+      Value.new(
+        data: t,
+        operation: :tanh,
+        previous: [self],
+        _backward: lambda do |value|
+          self.add_grad!(value.grad * (1 - (t ** 2)))
+        end
+      )
+    end
+
+    def exp
+      Value.new(
+        data: Math.exp(self.data),
+        operation: :exp,
+        previous: [self],
+        _backward: lambda do |value|
+          self.add_grad!(value.grad * value.data)
+        end
+      )
+    end
+
+    def with_label(new_label)
+      self.class.new(
+        data: self.data,
+        label: new_label,
+        operation: self.operation,
+        previous: self.previous,
+        _backward: self._backward
+      )
+    end
+
+    def add_grad!(grad)
+      @grad ||= 0.0
+      @grad += grad
+      self
+    end
+
+    def zero_grad!
+      @grad = 0.0
+    end
+
+    def gradient_step!(learning_rate)
+      # This could be written as -learning_rate but this is harder to miss
+      @data += -1 * learning_rate * self.grad
+    end
+
+    def backward!
+      add_grad!(1)
+      Micrograd::TopoSort.new(self).call.reverse.map { |node| node._backward.call(node) }
+    end
+
+    def generate_image
+      Visualizer.new(self).generate_image
+    end
+
+    def coerce(other)
+      if other.is_a?(Numeric)
+        [Value[scalar: other], self]
+      else
+        raise TypeError.new("Cannot coerce #{other.class} into Value")
+      end
+    end
+  end
+end

data/lib/micrograd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Micrograd
+  VERSION = "0.1.0"
+end

data/lib/micrograd/visualizer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Micrograd
+  class Visualizer
+    attr_reader :node, :output_file
+
+    def initialize(node, output_file: "graph.svg")
+      @node = node
+      @output_file = output_file
+    end
+
+    def generate_image
+      Open3.popen3("d2", "-", "--layout=elk") do |stdin, stdout, stderr, wait_thr|
+        stdin.puts(to_d2)
+        stdin.close
+
+        if wait_thr.value.success?
+          File.write(output_file, stdout.read)
+        else
+          raise "Error: #{stderr}"
+        end
+      end
+    end
+
+    private
+
+    def to_d2
+      nodes, edges = build_graph(node)
+      d2_representation = "direction: right\n"
+      d2_representation += nodes.map do |node_id, node|
+        label_or_operation = node.label || node.operation
+        rounded_data = round(node.data)
+        grad_line = "grad: #{round(node.grad)}" if node.grad
+        data_line = [label_or_operation, rounded_data].compact.join(": ")
+        contents = [data_line, grad_line].compact.join("\\n")
+        %("#{node_id}": #{contents}\n)
+      end.join
+      d2_representation += edges.map { |from, to, op| %(#{from} -> "#{to}": #{op}\n) }.join
+      d2_representation
+    end
+
+    def build_graph(node, nodes = {}, edges = [])
+      return [nodes, edges] if nodes.key?(node.id)
+
+      new_nodes = nodes.merge(node.id => node)
+      new_edges = edges + node.previous.map { |prev| [prev.id, node.id, node.operation] }
+      node.previous.reduce([new_nodes, new_edges]) { |acc, prev| build_graph(prev, *acc) }
+    end
+
+    def round(float)
+      format("%.4f", float)
+    end
+  end
+end

data/lib/micrograd.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "training"
+
+module Micrograd
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: micrograd-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Collins
+bindir: bin
+cert_chain: []
+date: 2025-03-28 00:00:00.000000000 Z
+dependencies: []
+email:
+- sean@cllns.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/micrograd.rb
+- lib/micrograd/examples.rb
+- lib/micrograd/layer.rb
+- lib/micrograd/mlp.rb
+- lib/micrograd/neuron.rb
+- lib/micrograd/topo_sort.rb
+- lib/micrograd/training.rb
+- lib/micrograd/value.rb
+- lib/micrograd/version.rb
+- lib/micrograd/visualizer.rb
+homepage: https://github.com/cllns/micrograd-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cllns/micrograd-rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby implementation of micrograd
+test_files: []