@aleph-ai/tinyaleph 1.0.0

package/docs/theory/03-phase-synchronization.md

@@ -0,0 +1,364 @@
+# Phase Synchronization
+
+## The Kuramoto Model
+
+The **Kuramoto model** is a mathematical model for describing synchronization in systems of coupled oscillators. It captures a profound phenomenon: when oscillators interact, they tend to align their phases—to "agree" on a common rhythm.
+
+### The Governing Equation
+
+```
+dθᵢ/dt = ωᵢ + (K/N) Σⱼ sin(θⱼ - θᵢ)
+```
+
+Where:
+- θᵢ is the phase of oscillator i
+- ωᵢ is its natural frequency
+- K is the coupling strength
+- N is the number of oscillators
+- The sum is over all other oscillators
+
+### Semantic Interpretation
+
+| Kuramoto Concept | Semantic Meaning |
+|-----------------|------------------|
+| Oscillator | A concept with its prime frequency |
+| Phase | Where the concept is in its "meaning cycle" |
+| Frequency | The intrinsic nature of the concept |
+| Coupling K | How strongly concepts influence each other |
+| Synchronization | Conceptual agreement/understanding |
+
+---
+
+## The Oscillator Class
+
+Individual oscillators start **quiescent** (amplitude = 0) and must be **excited** by input:
+
+```javascript
+class Oscillator {
+  constructor(frequency, phase = 0, amplitude = 0) {
+    this.freq = frequency;
+    this.phase = phase;
+    this.amplitude = amplitude;  // Starts quiescent!
+    this.phaseHistory = [];
+  }
+  
+  tick(dt, coupling = 0) {
+    this.phase = (this.phase + 2 * Math.PI * this.freq * dt + coupling) % (2 * Math.PI);
+    this.phaseHistory.push(this.phase);
+    if (this.phaseHistory.length > 100) this.phaseHistory.shift();
+  }
+  
+  excite(amount = 0.5) {
+    this.amplitude = Math.min(1, this.amplitude + amount);
+  }
+  
+  decay(rate = 0.02, dt = 1) {
+    this.amplitude *= (1 - rate * dt);
+  }
+}
+```
+
+### Key Properties
+
+- **Frequency**: Determined by the corresponding prime
+- **Phase**: Evolves according to frequency + coupling
+- **Amplitude**: Represents activation level (0 = inactive, 1 = fully active)
+- **Phase History**: Enables Lyapunov stability analysis
+
+---
+
+## The Kuramoto Model Implementation
+
+```javascript
+class KuramotoModel extends OscillatorBank {
+  constructor(frequencies, couplingStrength = 0.3) {
+    super(frequencies);
+    this.K = couplingStrength;
+  }
+  
+  kuramotoCoupling(osc) {
+    let coupling = 0;
+    for (const other of this.oscillators) {
+      if (other !== osc) {
+        coupling += Math.sin(other.phase - osc.phase);
+      }
+    }
+    return this.K * coupling / this.oscillators.length;
+  }
+  
+  tick(dt) {
+    // Each oscillator feels the pull of all others
+    super.tick(dt, (osc) => this.kuramotoCoupling(osc) * dt);
+    
+    // Amplitudes decay over time
+    for (const osc of this.oscillators) {
+      osc.decay(0.02, dt);
+    }
+  }
+}
+```
+
+### The Coupling Term
+
+The coupling term `K × sin(θⱼ - θᵢ)` has beautiful properties:
+- When θⱼ > θᵢ: positive, pulls oscillator i forward
+- When θⱼ < θᵢ: negative, pulls oscillator i backward
+- Net effect: phases move toward each other
+- Strength proportional to K
+
+---
+
+## The Order Parameter
+
+The **order parameter** r measures how synchronized the oscillators are:
+
+```javascript
+orderParameter() {
+  let sx = 0, sy = 0;
+  for (const osc of this.oscillators) {
+    sx += osc.amplitude * Math.cos(osc.phase);
+    sy += osc.amplitude * Math.sin(osc.phase);
+  }
+  const N = this.oscillators.length;
+  return Math.sqrt((sx/N)**2 + (sy/N)**2);
+}
+```
+
+### Interpretation
+
+| Order Parameter | Meaning |
+|-----------------|---------|
+| r ≈ 0 | Desynchronized (incoherent, confused) |
+| r ≈ 0.5 | Partially synchronized (emerging understanding) |
+| r ≈ 1 | Fully synchronized (coherent understanding) |
+
+The order parameter is Aleph's measure of **conceptual coherence**.
+
+---
+
+## Mean Phase
+
+The **mean phase** represents the "average direction" of the oscillator ensemble:
+
+```javascript
+meanPhase() {
+  let sx = 0, sy = 0, ta = 0;
+  for (const osc of this.oscillators) {
+    sx += osc.amplitude * Math.cos(osc.phase);
+    sy += osc.amplitude * Math.sin(osc.phase);
+    ta += osc.amplitude;
+  }
+  return ta > 0 ? Math.atan2(sy/ta, sx/ta) : 0;
+}
+```
+
+When concepts synchronize, the mean phase indicates the dominant conceptual direction.
+
+---
+
+## Excitation by Primes
+
+When input arrives, we excite the oscillators corresponding to input primes:
+
+```javascript
+exciteByPrimes(primes, primeList, amount = 0.5) {
+  const primeSet = new Set(primes);
+  for (let i = 0; i < this.oscillators.length && i < primeList.length; i++) {
+    if (primeSet.has(primeList[i])) {
+      this.oscillators[i].excite(amount);
+    }
+  }
+}
+```
+
+### Excitation Flow
+
+```
+Input: "love and wisdom"
+
+1. Tokenize → ["love", "wisdom"]
+2. Encode → love = [2,3,5], wisdom = [2,7,11]
+3. Primes → {2, 3, 5, 7, 11}
+4. Excite oscillators for primes 2, 3, 5, 7, 11
+5. Oscillators begin at different phases
+6. Coupling causes synchronization
+7. Order parameter rises as concepts unify
+```
+
+---
+
+## Weighted Amplitudes
+
+The engine uses amplitude-weighted phase values for state construction:
+
+```javascript
+getWeightedAmplitudes() {
+  return this.oscillators.map(o => o.amplitude * Math.sin(o.phase));
+}
+```
+
+This creates a state vector where:
+- Excited oscillators contribute based on their current phase
+- Quiescent oscillators contribute nothing
+- The overall pattern reflects the dynamic state of the concept field
+
+---
+
+## Pairwise Coherence
+
+Detailed coherence between oscillator pairs:
+
+```javascript
+pairwiseCoherence() {
+  const N = this.oscillators.length;
+  let total = 0, count = 0;
+  for (let i = 0; i < N; i++) {
+    for (let j = i + 1; j < N; j++) {
+      total += Math.cos(this.oscillators[i].phase - this.oscillators[j].phase);
+      count++;
+    }
+  }
+  return count > 0 ? total / count : 0;
+}
+```
+
+High pairwise coherence indicates that concepts are aligning, even before full synchronization.
+
+---
+
+## Critical Coupling
+
+There's a critical coupling strength Kc below which synchronization cannot occur:
+
+```
+Kc ≈ 2 / (π × g(0))
+```
+
+Where g(0) is the value of the frequency distribution at its center.
+
+- **K < Kc**: Oscillators remain desynchronized
+- **K > Kc**: Spontaneous synchronization emerges
+- **K >> Kc**: Fast, complete synchronization
+
+In Aleph, we use **adaptive coupling** that adjusts based on Lyapunov stability:
+
+```javascript
+function adaptiveCoupling(baseCoupling, lyapunovExponent, gain = 0.5) {
+  if (lyapunovExponent < -0.1) return baseCoupling * (1 + gain);  // Stable: increase
+  if (lyapunovExponent > 0.1) return baseCoupling * (1 - gain);   // Chaotic: decrease
+  return baseCoupling;  // Marginal: maintain
+}
+```
+
+---
+
+## The Physics-Meaning Bridge
+
+The oscillator dynamics create a bridge between physics and meaning:
+
+```
+                    PHYSICAL                         SEMANTIC
+                    ========                         ========
+                    
+Oscillator          Resonating entity    ←→    Active concept
+                    
+Phase               Position in cycle    ←→    State of meaning
+                    
+Frequency           Natural rate         ←→    Concept identity
+                    
+Coupling            Interaction force    ←→    Semantic influence
+                    
+Synchronization     Phase alignment      ←→    Understanding
+                    
+Order parameter     Coherence measure    ←→    Clarity of thought
+```
+
+---
+
+## Field-Based Computation
+
+Aleph performs **field-based computation**—the answer emerges from oscillator dynamics:
+
+```javascript
+// Main processing loop
+run(input) {
+  // 1. Encode input to primes
+  const inputPrimes = this.backend.encode(input);
+  
+  // 2. Excite corresponding oscillators
+  this.excite(inputPrimes);
+  
+  // 3. Evolve the field
+  for (let i = 0; i < maxSteps; i++) {
+    this.tick(dt);
+    
+    // 4. Sample coherent frames
+    if (orderParameter > threshold) {
+      frames.push(currentState);
+    }
+    
+    // 5. Check for stable coherence
+    if (orderParameter > stableThreshold) {
+      break;  // Coherent state reached
+    }
+  }
+  
+  // 6. Decode from best frame
+  return this.decode(bestFrame);
+}
+```
+
+The answer isn't calculated—it **crystallizes** from the dynamics.
+
+---
+
+## Transient vs. Steady State
+
+Aleph captures the **transient response**, not just the steady state:
+
+```javascript
+// Track differential response
+for (let i = 0; i < maxEvolutionSteps; i++) {
+  this.tick(dt);
+  
+  // Compute input-weighted differential response
+  let inputResponse = 0, otherResponse = 0;
+  
+  for (let j = 0; j < primeList.length; j++) {
+    const diff = |current[j]| - |baseline[j]|;
+    if (inputPrimes.has(primeList[j])) {
+      inputResponse += diff;  // Input primes responding
+    } else {
+      otherResponse += |diff|;  // Other primes responding
+    }
+  }
+  
+  const differential = inputResponse - otherResponse * 0.3;
+  
+  // Sample frames with good differential (not just high order)
+  if (differential > 0) {
+    frames.push(currentFrame);
+  }
+}
+```
+
+This captures how the field **responds to input** rather than just its final state.
+
+---
+
+## Summary
+
+Phase synchronization provides:
+
+1. **Dynamic representation** of concepts as oscillators
+2. **Natural synchronization** through Kuramoto coupling
+3. **Order parameter** as coherence measure
+4. **Transient capture** of input-specific responses
+5. **Adaptive coupling** for stability control
+6. **Field-based computation** where answers emerge from dynamics
+
+The oscillator model is the heartbeat of semantic computation.
+
+---
+
+## Next: [Entropy and Reasoning →](./04-entropy-reasoning.md)

package/docs/theory/04-entropy-reasoning.md

@@ -0,0 +1,348 @@
+# Entropy and Reasoning
+
+## Information-Theoretic Foundations
+
+Aleph treats reasoning as **entropy minimization**. This framing connects to fundamental physics: systems naturally evolve toward states of maximum entropy (thermodynamics), but intelligent systems can locally reduce entropy by organizing information.
+
+### Shannon Entropy
+
+The Shannon entropy of a probability distribution measures uncertainty:
+
+```javascript
+function shannonEntropy(probabilities) {
+  let H = 0;
+  for (const p of probabilities) {
+    if (p > 1e-10) H -= p * Math.log2(p);
+  }
+  return H;
+}
+```
+
+For a hypercomplex state, we compute entropy from the normalized component magnitudes:
+
+```javascript
+function stateEntropy(hypercomplex) {
+  const n = hypercomplex.norm();
+  if (n < 1e-10) return 0;
+  const probs = hypercomplex.c.map(v => (v / n) ** 2);
+  return shannonEntropy(probs);
+}
+```
+
+---
+
+## Entropy as Confusion
+
+| Entropy | Interpretation |
+|---------|---------------|
+| H ≈ 0 | State concentrated on one axis → pure concept |
+| H ≈ 1 | State on two axes → binary distinction |
+| H ≈ 2 | State on ~4 axes → moderate complexity |
+| H ≈ 3 | State spread → confusion, unresolved meaning |
+| H ≈ 4 | Maximum spread → maximum uncertainty |
+
+### Example: Entropy Evolution
+
+```
+Input: "Is justice possible without mercy?"
+
+Initial state:
+  H = 3.2 (high entropy)
+  Concepts: justice, possible, without, mercy
+  State spread across many dimensions
+
+After transforms:
+  H = 1.4 (lower entropy)  
+  Concepts: balance, wisdom
+  State concentrated on fewer dimensions
+
+Interpretation:
+  The question resolved to a simpler understanding
+```
+
+---
+
+## Reasoning as Entropy Minimization
+
+The engine seeks transforms that reduce entropy:
+
+```javascript
+reason(primes) {
+  const transforms = this.backend.getTransforms();
+  let current = [...new Set(primes)];
+  let state = this.backend.primesToState(current);
+  let H = stateEntropy(state);
+  const steps = [];
+  
+  for (let i = 0; i < maxSteps && H > threshold; i++) {
+    let best = null, bestH = H, bestPrimes = current;
+    
+    // Search for entropy-reducing transform
+    for (const transform of transforms) {
+      const newPrimes = this.backend.applyTransform(current, transform);
+      
+      // Skip if no change
+      if (arraysEqual(newPrimes, current)) continue;
+      
+      const newState = this.backend.primesToState(newPrimes);
+      const newH = stateEntropy(newState);
+      
+      if (newH < bestH) {
+        best = transform;
+        bestH = newH;
+        bestPrimes = newPrimes;
+      }
+    }
+    
+    if (!best) break;  // No improvement possible
+    
+    steps.push({
+      step: i + 1,
+      transform: best.name,
+      entropyDrop: H - bestH
+    });
+    
+    current = bestPrimes;
+    H = bestH;
+  }
+  
+  return { primes: current, entropy: H, steps };
+}
+```
+
+### The Algorithm
+
+1. Start with input prime set
+2. Compute initial state and entropy
+3. For each possible transform:
+   - Apply transform to get new primes
+   - Compute new state and entropy
+   - Track if this reduces entropy
+4. Apply best transform
+5. Repeat until entropy below threshold or no improvement
+
+---
+
+## Transforms as Semantic Rewrites
+
+Transforms are semantic rewrite rules:
+
+```javascript
+const transform = {
+  n: "question_to_answer",
+  q: [curiosity, unknown],     // Query primes (must be present)
+  r: [understanding, known]    // Result primes (replace query)
+};
+```
+
+### Transform Application
+
+```javascript
+applyTransform(inputPrimes, transform) {
+  const inputSet = new Set(inputPrimes);
+  
+  // Check if query primes are present
+  if (!transform.q.some(p => inputSet.has(p))) {
+    return inputPrimes;  // No match
+  }
+  
+  // Protect core primes
+  if (transform.q.some(p => this.corePrimes.has(p))) {
+    return inputPrimes;
+  }
+  
+  // Apply: remove query primes, add result primes
+  const kept = inputPrimes.filter(p => 
+    this.corePrimes.has(p) || !transform.q.includes(p)
+  );
+  return [...new Set([...kept, ...transform.r])];
+}
+```
+
+### Transform Types
+
+| Type | Example | Effect |
+|------|---------|--------|
+| **Simplification** | complex → simple | Reduces prime count |
+| **Unification** | A ∪ B → C | Merges concepts |
+| **Abstraction** | instances → type | Moves up hierarchy |
+| **Resolution** | question → answer | Resolves inquiry |
+
+---
+
+## Coherence Between States
+
+Coherence measures alignment between states:
+
+```javascript
+function coherence(state1, state2) {
+  const n1 = state1.norm();
+  const n2 = state2.norm();
+  if (n1 < 1e-10 || n2 < 1e-10) return 0;
+  return Math.abs(state1.dot(state2)) / (n1 * n2);
+}
+```
+
+### Interpretation
+
+- **Coherence = 1**: States identical (same meaning)
+- **Coherence = 0**: States orthogonal (unrelated)
+- **Coherence = 0.7+**: High alignment (related meanings)
+
+High coherence with low entropy indicates clear, unified understanding.
+
+---
+
+## Mutual Information
+
+For coupled oscillator banks, mutual information measures shared structure:
+
+```javascript
+function mutualInformation(bank1, bank2) {
+  let corr = 0;
+  const n = Math.min(bank1.oscillators.length, bank2.oscillators.length);
+  for (let i = 0; i < n; i++) {
+    corr += Math.cos(bank1.oscillators[i].phase - bank2.oscillators[i].phase);
+  }
+  return Math.max(0, corr / n);
+}
+```
+
+High mutual information indicates that two concept fields are resonating together.
+
+---
+
+## Relative Entropy (KL Divergence)
+
+KL divergence measures how one distribution differs from another:
+
+```javascript
+function relativeEntropy(p, q) {
+  let kl = 0;
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] > 1e-10 && q[i] > 1e-10) {
+      kl += p[i] * Math.log2(p[i] / q[i]);
+    }
+  }
+  return kl;
+}
+```
+
+This quantifies how "surprising" distribution p is relative to expectation q.
+
+---
+
+## Joint Entropy
+
+For two states together:
+
+```javascript
+function jointEntropy(state1, state2) {
+  const n1 = state1.norm(), n2 = state2.norm();
+  if (n1 < 1e-10 || n2 < 1e-10) return 0;
+  
+  // Create joint probability distribution
+  const probs = [];
+  for (let i = 0; i < state1.dim; i++) {
+    for (let j = 0; j < state2.dim; j++) {
+      const p1 = (state1.c[i] / n1) ** 2;
+      const p2 = (state2.c[j] / n2) ** 2;
+      probs.push(p1 * p2);
+    }
+  }
+  return shannonEntropy(probs);
+}
+```
+
+Joint entropy captures the total information in the combined system.
+
+---
+
+## Oscillator Entropy
+
+Entropy from the oscillator bank's amplitude distribution:
+
+```javascript
+function oscillatorEntropy(bank) {
+  const amplitudes = bank.getAmplitudes();
+  const total = amplitudes.reduce((a, b) => a + b, 0);
+  if (total < 1e-10) return 0;
+  const probs = amplitudes.map(a => a / total);
+  return shannonEntropy(probs);
+}
+```
+
+This measures how evenly "excited" the oscillator bank is.
+
+---
+
+## The Collapse Integral
+
+Entropy accumulates over time, driving toward collapse:
+
+```javascript
+// In engine tick
+this.collapseIntegral += this.entropy * dt * 0.1;
+```
+
+When the collapse integral exceeds a threshold and other conditions are met, the state "collapses" to a definite value—modeling the "aha!" moment of insight.
+
+---
+
+## Reasoning Example
+
+```
+Query: "What is the relationship between freedom and responsibility?"
+
+Step 0: Encode
+  primes = [freedom, responsibility] = [23, 47, 19, 53]
+  entropy = 3.4
+
+Step 1: Transform (abstraction)
+  "freedom" → "self-determination"
+  primes = [self, determination, responsibility]
+  entropy = 2.9 (↓0.5)
+
+Step 2: Transform (unification)
+  "self-determination" + "responsibility" → "agency"
+  primes = [agency]
+  entropy = 1.2 (↓1.7)
+
+Result: 
+  The concepts unified into "agency"
+  Entropy dropped from 3.4 to 1.2
+  Understanding crystallized
+```
+
+---
+
+## The Insight
+
+Entropy minimization as reasoning has profound implications:
+
+1. **Reasoning is physical**: It follows thermodynamic principles
+2. **Understanding is compression**: Fewer primes = clearer meaning
+3. **Confusion is entropy**: High H = unresolved complexity
+4. **Insight is collapse**: Sudden entropy drop = "aha!"
+5. **Wisdom is simplicity**: Low H stable states are wise
+
+This connects the cognitive experience of understanding to rigorous information theory.
+
+---
+
+## Summary
+
+Entropy and reasoning in Aleph:
+
+1. **Shannon entropy** measures conceptual confusion
+2. **Transforms** are semantic rewrite rules
+3. **Reasoning** minimizes entropy through transforms
+4. **Coherence** measures alignment between states
+5. **Collapse integral** accumulates toward insight moments
+6. **Understanding** = low entropy, high coherence
+
+Reasoning is the process of organizing meaning toward clarity.
+
+---
+
+## Next: [Non-Commutativity →](./05-non-commutativity.md)