manim-mcp 0.1.0

package/references/composer/references/domain-planning-guides/linear-algebra-planning.md

@@ -0,0 +1,169 @@
+# Linear Algebra Video Planning Guide
+
+Based on the Essence of Linear Algebra series (2016), supplemental linear algebra content across multiple years, and cross-cutting patterns from the 3b1b codebase.
+
+---
+
+## Core Visual Language
+
+### The Grid Transformation (THE signature visual)
+
+Every linear algebra concept in 3b1b is grounded in the `NumberPlane` grid transformation. This is non-negotiable -- it IS the visual language.
+
+```python
+plane = NumberPlane()
+i_hat = Vector(RIGHT, color=GREEN)    # Always GREEN
+j_hat = Vector(UP, color=RED)          # Always RED
+```
+
+**Color conventions (from EoLA):**
+- i-hat (first basis vector): GREEN
+- j-hat (second basis vector): RED
+- k-hat (third basis vector, 3D): Typically BLUE or MAROON
+- Arbitrary vector v: YELLOW
+- Grid lines: BLUE variations (BLUE_D, BLUE_B)
+- Determinant area: Fill with opacity, color by sign (positive=BLUE, negative=RED)
+- Eigenspace: Distinct color, often TEAL or MAROON
+
+### Transformation Matrix Display
+
+Always show the matrix alongside the grid transformation:
+```python
+matrix = Matrix([[a, b], [c, d]])
+# Position matrix to the side (usually upper-right or lower-right)
+# Column 1 colored GREEN (where i-hat lands)
+# Column 2 colored RED (where j-hat lands)
+```
+
+---
+
+## Chapter Planning by Topic
+
+### Vectors
+
+**Key scenes:**
+1. Three perspectives (physics arrow, CS list, mathematician's abstract element)
+2. Addition as tip-to-tail
+3. Scaling as stretching/shrinking
+4. Coordinates as scalars of basis vectors
+
+**Visual techniques:**
+- `Arrow` for vectors (NOT `Line` -- arrows have direction)
+- `vector_coordinate_label()` for showing [x, y] next to a vector
+- Color-coded components: x-component in one color, y-component in another
+
+### Linear Transformations
+
+**Key scenes:**
+1. Show transformation by tracking grid lines
+2. "Where do i-hat and j-hat land?" -- the key insight
+3. Any vector v = xi + yj transforms to x(new i) + y(new j)
+4. `apply_matrix()` on NumberPlane for the dramatic transformation
+
+**The critical insight to sell:** If you know where the basis vectors go, you know where EVERYTHING goes. This is why matrices have two columns -- one for each basis vector's landing spot.
+
+### Matrix Multiplication
+
+**Key scenes:**
+1. Apply transformation A
+2. Apply transformation B
+3. "What single transformation does both?" -> That's AB
+4. Order matters: AB != BA (show a rotation then shear vs shear then rotation)
+
+**Visual technique:** Apply one matrix, then a second, then show the composed matrix gives the same result.
+
+### Determinant
+
+**Key scenes:**
+1. Unit square with area 1
+2. Transform: watch the area change
+3. Determinant = factor by which areas scale
+4. Negative determinant = orientation flip (grid "flips")
+5. Determinant 0 = squished to lower dimension
+
+**Visual techniques:**
+- Fill the unit square with semi-transparent color
+- Show area value updating as transformation is applied
+- Use `SurroundingRectangle` or `Polygon` for area visualization
+- Animate orientation flip by showing handedness (clockwise vs counterclockwise)
+
+### Eigenvectors and Eigenvalues
+
+**Key scenes:**
+1. Apply transformation: most vectors change direction
+2. But SOME vectors stay on their span (just scaled)
+3. These are eigenvectors; the scaling factor is the eigenvalue
+4. Eigenbasis: if all basis vectors are eigenvectors, the matrix is diagonal
+
+**Visual techniques:**
+- Highlight eigenvectors with distinct color before and after transformation
+- Show the "span line" that the eigenvector stays on
+- Arrow staying on its line while other arrows rotate
+
+---
+
+## The "Your Coordinates vs Jennifer's Coordinates" Pattern
+
+From EoLA Chapter 10 (Change of Basis). This is a powerful pedagogical device: personify different bases as different people's "languages."
+
+**Structure:**
+1. Introduce "your" standard basis (i-hat, j-hat)
+2. Introduce "Jennifer's" basis (different vectors)
+3. Same vector, described differently in each system
+4. The change-of-basis matrix is a "translator"
+
+---
+
+## 3D Linear Algebra
+
+From EoLA Chapter 5 and `_2015/three_dimensions.py`:
+
+**Key differences from 2D:**
+- Three basis vectors: i-hat, j-hat, k-hat
+- 3x3 matrices
+- Determinant = volume scaling
+- Cross product as the "third vector" from two inputs
+
+**Visual techniques:**
+- `ThreeDScene` or `InteractiveScene` with `frame.reorient()`
+- `set_floor_plane("xz")` for ground-plane perspective
+- `always_sort_to_camera()` for depth ordering
+- Ambient camera rotation: `frame.add_updater(lambda m, dt: m.increment_theta(-0.1 * dt))`
+
+---
+
+## Equation Patterns
+
+### Common LaTeX with Color Coding
+
+```python
+# Matrix-vector product
+Tex(R"""
+    \begin{bmatrix} a & b \\ c & d \end{bmatrix}
+    \begin{bmatrix} x \\ y \end{bmatrix}
+    = x \begin{bmatrix} a \\ c \end{bmatrix}
+    + y \begin{bmatrix} b \\ d \end{bmatrix}
+""", t2c={
+    "a": GREEN, "c": GREEN,  # First column = i-hat landing
+    "b": RED, "d": RED,       # Second column = j-hat landing
+    "x": YELLOW, "y": YELLOW, # Input vector components
+})
+```
+
+### Eigenvalue equation
+```python
+Tex(R"A \vec{v} = \lambda \vec{v}", t2c={
+    R"\vec{v}": MAROON,
+    R"\lambda": YELLOW,
+})
+```
+
+---
+
+## Common Pitfalls in Linear Algebra Videos
+
+1. **Jumping to computation too fast**: Always show the GEOMETRIC meaning before the arithmetic.
+2. **Not animating the transformation**: Static before/after images don't work. The viewer needs to WATCH the grid move.
+3. **Treating matrix multiplication as "row times column"**: This is the computation, not the meaning. The meaning is composition of transformations.
+4. **Ignoring the null space**: When the determinant is 0, SHOW the squishing. This is often more illuminating than the non-degenerate case.
+5. **Abstract spaces without grounding**: If discussing function spaces, first show the concrete 2D analogy, THEN generalize.

package/references/composer/references/domain-planning-guides/ml-planning.md

@@ -0,0 +1,286 @@
+# Machine Learning Video Planning Guide
+
+Based on the Neural Networks series (2017), Transformers series (2024), and related ML content across the 3b1b codebase.
+
+---
+
+## Core Visual Language
+
+### Neural Network Visualization
+
+**`NeuralNetwork` mobject** (`_2024/transformers/helpers.py`):
+```python
+class NeuralNetwork(VGroup):
+    def __init__(self, layer_sizes=[5, 10, 5]):
+        self.layers = VGroup(VGroup(Dot() for _ in range(n)) for n in layer_sizes)
+        self.lines = VGroup(...)  # Connections between layers
+
+    def randomize_line_style(self):
+        # Stroke widths and colors vary by weight value
+
+    def randomize_layer_values(self):
+        # Dot fill opacities represent activation levels
+```
+
+**Key principle**: Dot opacity = activation level. Connection stroke width = weight magnitude. Connection color = weight sign (blue=positive, red=negative).
+
+### Weight Matrix Visualization
+
+**`WeightMatrix`** (`_2024/transformers/helpers.py`):
+```python
+class WeightMatrix(DecimalMatrix):
+    # Each entry colored by value_to_color()
+    # Blue for positive, Red for negative
+    # Intensity proportional to magnitude
+
+def value_to_color(value):
+    # Positive -> BLUE gradient
+    # Negative -> RED gradient
+    # Near zero -> dark/muted
+```
+
+### Embedding Visualization
+
+**`NumericEmbedding`** -- Column vector with color-coded entries:
+```python
+class NumericEmbedding(WeightMatrix):
+    def __init__(self, length=8):
+        super().__init__(shape=(length, 1))
+```
+
+**`EmbeddingArray`** -- Row of embeddings for a sequence:
+```python
+class EmbeddingArray(VGroup):
+    # Array of NumericEmbedding objects
+    # With brackets and dot separators
+```
+
+### Machine Metaphor
+
+**`MachineWithDials`** -- Visual metaphor for model parameters:
+```python
+class MachineWithDials(VGroup):
+    def random_change_animation(self):
+        # Dials rotate to new values
+        # Represents gradient descent step
+```
+
+---
+
+## Topic Planning
+
+### Neural Network Basics
+
+**Series structure (from `_2017/nn/`):**
+
+Part 1: What IS a neural network?
+- Start with MNIST digit recognition
+- `PixelsAsSquares`: show raw pixel input
+- Layer-by-layer architecture
+- Activation function (sigmoid, ReLU)
+- "What does each neuron represent?"
+
+Part 2: Gradient descent
+- Cost function visualization (landscape with valleys)
+- Gradient as direction of steepest descent
+- Learning rate as step size
+- "Ball rolling downhill" analogy
+
+Part 3: Backpropagation intuition
+- Which weights matter most?
+- Chain rule through the network
+- Sensitivity analysis
+
+Part 4: Backpropagation calculus
+- Full derivative computation
+- Matrix notation
+
+**Pixel visualization** (`_2017/nn/part1.py`):
+```python
+class PixelsAsSquares(VGroup):
+    # Converts image to grid of colored squares
+    # Each square's opacity = pixel brightness
+```
+
+### Transformer Architecture
+
+**Series structure (from `_2024/transformers/`):**
+
+**High-Level Flow** (`network_flow.py`):
+```python
+class HighLevelNetworkFlow(InteractiveScene):
+    def show_initial_text_embedding(self):
+        # Tokenization -> embedding vectors
+
+    def progress_through_attention_block(self):
+        # 3D block with arc-based attention
+
+    def progress_through_mlp_block(self):
+        # Neuron clusters with weighted connections
+
+    def mention_repetitions(self):
+        # "Many repetitions" brace
+
+    def show_unembedding(self):
+        # Final distribution over vocabulary
+```
+
+**Attention Visualization** (`attention.py`):
+- Query-Key dot product as "looking at" another token
+- Softmax as normalization (making weights sum to 1)
+- Value vectors weighted and summed
+- Arc-based visual: arcs between token positions
+
+```python
+class ContextAnimation(LaggedStart):
+    # Curved arcs between embedding positions
+    # Color and width encode attention weight
+```
+
+**Embedding Space** (`embedding.py`):
+- Tokenization with tiktoken
+- Color-coded token rectangles
+- Word2Vec demonstrations (king - man + woman = queen)
+
+```python
+def break_into_tokens(phrase):
+    # Uses tiktoken to split text into GPT tokens
+
+def get_piece_rectangles(words):
+    # Colored rectangles around each token
+```
+
+**Auto-regression** (`auto_regression.py`):
+- Live GPT-2 inference in the animation
+- Bar chart of next-token probabilities
+- Random sampling with animated highlight
+
+```python
+def gpt2_predict_next_token(text, n_shown=7):
+    tokenizer = get_gpt2_tokenizer()
+    model = get_gpt2_model()
+    # Returns top tokens and probabilities
+```
+
+**The full auto-regressive loop:**
+```python
+class SimpleAutogregression(InteractiveScene):
+    def new_selection_cycle(self, text_mob, ...):
+        self.animate_text_input(text_mob, machine)
+        bar_groups = self.animate_prediction_output(machine, self.cur_str)
+        self.animate_random_sample(bar_groups)
+        new_text_mob = self.animate_word_addition(bar_groups, text_mob, ...)
+```
+
+### ML Taxonomy
+
+**From `_2024/transformers/ml_basics.py`:**
+
+Nested boxes showing: AI > Machine Learning > Deep Learning > Transformers
+
+```python
+class MLWithinDeepL(InteractiveScene):
+    def get_titled_box(self, text, color):
+        title = Text(text)
+        box = Rectangle(...)
+        box.set_fill(interpolate_color(BLACK, color, opacity), 1)
+        box.set_stroke(color, 2)
+```
+
+---
+
+## The 3D Block Metaphor
+
+Transformer blocks rendered as 3D prisms create a visceral sense of data flowing through layers:
+
+```python
+blocks = VGroup(VPrism(3, 2, 0.2) for n in range(10))
+blocks.set_fill(GREY_D, 1)
+blocks.set_shading(0.25, 0.5, 0.2)
+blocks.arrange(OUT)
+blocks.rotate(self.machine_phi, RIGHT, about_edge=OUT)
+blocks.rotate(self.machine_theta, UP, about_edge=OUT)
+```
+
+Data flows INTO the stack, through each layer, and OUT the other side. This is more engaging than flat 2D diagrams.
+
+---
+
+## Live Model Integration
+
+A unique technique in the Transformer series: actual model inference happens during the animation.
+
+**GPT-2** (local, via HuggingFace transformers):
+```python
+from transformers import GPT2Tokenizer, GPT2LMHeadModel
+import torch
+
+tokenizer = GPT2Tokenizer.from_pretrained('gpt2')
+model = GPT2LMHeadModel.from_pretrained('gpt2')
+```
+
+**GPT-3** (API, via OpenAI):
+```python
+openai.api_key = os.getenv('OPENAI_KEY')
+response = openai.Completion.create(engine="gpt-3.5-turbo-instruct", ...)
+```
+
+**When to use live model integration:**
+- Demonstrating next-token prediction
+- Showing probability distributions over vocabulary
+- Illustrating temperature effects on sampling
+- Making the abstract architecture tangible
+
+---
+
+## Storytelling Patterns for ML
+
+### The "Black Box Then Open It" Pattern
+
+1. Show the model as a black box: input goes in, output comes out
+2. "But what's happening inside?"
+3. Open one component at a time
+4. By the end, the black box is transparent
+
+This is the structure of the entire Transformer series: Part 1 is the black box overview, subsequent parts open each component.
+
+### The "Why This Architecture?" Pattern
+
+Don't just explain what attention does -- explain why you'd INVENT it:
+1. "What problem are we solving?" (context mixing)
+2. "What's the naive approach?" (fully connected layers)
+3. "Why doesn't that scale?" (parameter explosion)
+4. "What if we could selectively attend?" (attention mechanism)
+
+### Concrete Before Abstract
+
+- Show MNIST before discussing abstract neural networks
+- Show GPT generating text before discussing transformer architecture
+- Show a specific attention pattern before the general mechanism
+
+---
+
+## Color Conventions for ML
+
+| Element | Color | Context |
+|---------|-------|---------|
+| Positive weights | BLUE gradient | Weight matrices |
+| Negative weights | RED gradient | Weight matrices |
+| Activation (high) | Bright/opaque | Neuron activations |
+| Activation (low) | Dark/transparent | Neuron activations |
+| Input data | BLUE | Network flow |
+| Output/prediction | GREEN or YELLOW | Network flow |
+| Attention arcs | Random bright colors | Token-to-token attention |
+| Embedding vectors | Color-coded per entry | Using value_to_color() |
+| Token rectangles | Pastel variants | Tokenization display |
+
+---
+
+## Common Pitfalls in ML Videos
+
+1. **Architecture diagram without motivation**: Don't show the transformer diagram first. Show the PROBLEM first (language modeling), then derive the architecture.
+2. **Too many numbers**: Weight matrices should be visualized as color grids, not numerical tables.
+3. **Skipping the "why" of softmax**: Don't just say "apply softmax." Show WHY you need to normalize, and why exponentials are the right way.
+4. **Static architecture diagrams**: Use animation to show data FLOWING through the network. LaggedStart, VShowPassingFlash, and arc animations create flow.
+5. **Ignoring scale**: Mention that real models have billions of parameters. The visualized 4x4 matrix represents a concept that scales to millions of dimensions.
+6. **Not grounding in real outputs**: Use actual model outputs (GPT-2 predictions) to make the abstract architecture tangible.

package/references/composer/references/domain-planning-guides/number-theory-planning.md

@@ -0,0 +1,187 @@
+# Number Theory Video Planning Guide
+
+Based on the Zeta function series (2016, 2022), prime spirals (2019), Euler's identity explorations, and number-theoretic content across the 3b1b codebase.
+
+---
+
+## Core Visual Language
+
+### Prime Number Visualization
+
+**Prime-colored number lines** (`_2022/zeta/part1.py`):
+```python
+PRIME_COLOR = YELLOW  # Primes are always YELLOW
+
+def get_prime_animation(self, numberline, prime):
+    point = numberline.n2p(prime)
+    dot = GlowDot(point, color=PRIME_COLOR)
+    arrow = Vector(DOWN, color=PRIME_COLOR)
+    return AnimationGroup(
+        ShowCreation(arrow),
+        MoveToTarget(dot, rate_func=rush_into),
+        numberline.numbers[prime].animate.set_color(PRIME_COLOR),
+    )
+```
+
+**Staggered prime reveal** using `time_span`:
+```python
+# Primes appear one at a time along the number line
+all_prime_animations.append(self.get_prime_animation(
+    numberline, n,
+    run_time=11,
+    time_span=(t, t + 1)  # Staggered timing within one play() call
+))
+```
+
+### Prime Spirals
+
+**From `_2019/spirals.py`:**
+
+Plot natural numbers in polar coordinates: number n at angle n radians, radius sqrt(n). Primes form visible spiral arms!
+
+**Ulam spiral variant**: Numbers on a square spiral, primes highlighted. Diagonal lines emerge.
+
+### Complex Plane Visualization
+
+**For zeta function, Euler's identity, etc.:**
+```python
+plane = ComplexPlane()
+# Plot function as a curve in the complex plane
+zeta_spiral = ParametricCurve(
+    lambda t: plane.n2p(complex(mpmath.zeta(complex(0.5, t)))),
+    t_range=(0, 42),
+)
+```
+
+**Phase coloring:**
+```python
+def z_to_color(z, sat=0.5, lum=0.5):
+    angle = math.atan2(z.imag, z.real)
+    return Color(hsl=(angle / TAU, sat, lum))
+```
+
+---
+
+## Topic Planning
+
+### The Riemann Zeta Function
+
+**From `_2016/zeta.py` and `_2022/zeta/part1.py`:**
+
+**Structure:**
+1. Start with the sum: 1 + 1/4 + 1/9 + ... = pi^2/6 (Basel problem hook)
+2. Generalize: zeta(s) = sum of 1/n^s
+3. Visualize on the number line (prime density)
+4. Move to the complex plane (analytic continuation)
+5. The critical strip and the hypothesis
+
+**Prime density visualization** (`ShowPrimeDensity`):
+- Number line with primes highlighted in YELLOW
+- Logarithmic weighting shows primes thin out
+- 1/ln(x) approximation overlaid
+
+**The zeta spiral**: Plotting zeta(1/2 + it) as a parametric curve in the complex plane. The zeros are where the curve passes through the origin.
+
+### Euler's Identity and e^(i*pi)
+
+**From `_2019/diffyq/` Part 5 and various:**
+
+**The rotational interpretation:**
+1. e^x as exponential growth on the number line
+2. Move to e^(it): now it's rotation in the complex plane
+3. e^(i*pi) = walking pi radians around the unit circle = -1
+4. "The most beautiful equation": e^(i*pi) + 1 = 0
+
+**Visual technique**: Point walking around the unit circle, with trail showing the path.
+
+### Modular Arithmetic and Number Patterns
+
+**From `_2019/spirals.py`:**
+
+**Residue patterns**: Color numbers by their residue mod n. In the spiral, same-residue numbers form spiral arms.
+
+**Clock arithmetic visualization**: Numbers on a circle, connecting those related by a multiplication.
+
+### Subset Sum and Integers (`_2022/puzzles/subsets.py`)
+
+**Set display:**
+```python
+def get_set_tex(values, max_shown=7):
+    # {1, 2, 3, ..., 2000}
+    # Handles ellipsis for large sets
+
+def get_subset_highlights(set_tex, subset):
+    # Rounded rectangles around specific elements
+```
+
+**Connection to zeta function**: The "unreasonable usefulness of complex numbers" for discrete problems.
+
+### Combinatorics and Counting
+
+**Moser's Circle Problem** (`_2023/moser_reboot/main.py`):
+
+```python
+def moser(n):
+    return choose(n, 4) + choose(n, 2) + 1
+```
+
+**Circle diagram**:
+```python
+points = [circle.pfp(a) for a in np.arange(0, 1, 1/n)]
+chords = VGroup(
+    Line(p1, p2).set_stroke(BLUE_B, 1)
+    for p1, p2 in it.combinations(points, 2)
+)
+```
+
+**Pascal's Triangle** (`_2018/eop/pascal.py`): Visual construction with highlighting of patterns (even/odd, mod 3, etc.)
+
+---
+
+## Storytelling Patterns for Number Theory
+
+### The "Pattern That Breaks" Hook
+
+Number theory is perfect for this: patterns seem obvious, then fail.
+
+- 1, 2, 4, 8, 16... then 31 (Moser)
+- Borwein integrals equal pi... until they don't
+- Fermat numbers seem prime... until they aren't
+
+### The "Unexpected Connection" Arc
+
+Number theory's greatest moments come from surprising connections:
+- Primes and pi (Basel problem, prime counting)
+- Primes and complex analysis (zeta function)
+- Discrete problems and continuous methods
+
+### The "Visualization Reveals Structure" Pattern
+
+Number theory concepts that seem abstract become obvious when visualized:
+- Prime spirals: plot numbers in polar coordinates, primes form patterns
+- Gaussian integers: lattice points in the complex plane
+- Modular arithmetic: clock face with connections
+
+---
+
+## Color Conventions for Number Theory
+
+| Element | Color | Context |
+|---------|-------|---------|
+| Primes | YELLOW | Universal across 3b1b |
+| Composite numbers | WHITE/GREY | Default |
+| Even numbers | BLUE | Residue coloring |
+| Odd numbers | RED | Residue coloring |
+| Complex values | Phase-colored (HSL by angle) | Zeta function |
+| Set elements (highlighted) | TEAL or MAROON | Subset problems |
+| Fibonacci/special sequences | GREEN | Sequence visualization |
+
+---
+
+## Common Pitfalls in Number Theory Videos
+
+1. **Starting with the formalism**: "Let s = sigma + it where sigma > 1..." -- NO. Start with "what's the sum of 1/n^2?"
+2. **Not enough visual grounding**: Number theory CAN feel abstract. Every concept needs a picture -- a number line, a spiral, a complex plane.
+3. **Assuming too much background**: Explain complex numbers before using them for zeta. Show what "analytic continuation" means visually.
+4. **Forgetting the "so what?"**: After proving a result, connect it to something the viewer cares about. "This is why your phone's encryption works."
+5. **Not using the surprise factor**: Number theory is FULL of surprises. Lean into them. "Wait, pi shows up in PRIME NUMBERS?"