@aleph-ai/tinyaleph 1.2.0 → 1.3.0

package/docs/design/BIOINFORMATICS_BACKEND_DESIGN.md

@@ -0,0 +1,493 @@
+# Bioinformatics Backend Design for TinyAleph
+
+## Executive Summary
+
+This document specifies a bioinformatics computation backend for tinyaleph that leverages the library's prime-resonance architecture to model biological systems. The design treats DNA as a prime-encoded information channel, molecular processes as entropy-minimizing transforms, and protein dynamics as coupled oscillator systems.
+
+**Core Thesis**: Biological computation follows the same prime-resonance principles as the tinyaleph framework:
+- Genetic information encodes as prime signatures (4 nucleotides, 20 amino acids → prime basis)
+- Central Dogma (DNA → RNA → Protein) maps to prime-preserving transform operators
+- Molecular dynamics (folding, binding) emerge from Kuramoto-like oscillator synchronization
+- Biological fitness maximization equals entropy minimization in the prime Hilbert space
+
+---
+
+## 1. Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    BioinformaticsBackend                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │
+│  │ DNA Encoder  │  │ Transform    │  │  Molecular Dynamics        │ │
+│  │ (4 primes)   │◄─┤ Pipeline     │◄─┤  (Kuramoto Coupling)       │ │
+│  └──────────────┘  └──────────────┘  └────────────────────────────┘ │
+│         │                 │                       │                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │
+│  │ RNA Encoder  │  │ Codon Table  │  │  Folding Energy Landscape  │ │
+│  │ (4 primes)   │  │ (64 primes)  │  │  (Entropy Surface)         │ │
+│  └──────────────┘  └──────────────┘  └────────────────────────────┘ │
+│         │                 │                       │                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │
+│  │ Protein      │  │ Mutation     │  │  Binding Affinity          │ │
+│  │ Encoder      │  │ Operators    │  │  (Resonance Scoring)       │ │
+│  │ (20 primes)  │  │              │  │                            │ │
+│  └──────────────┘  └──────────────┘  └────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+         ┌────────────────────┼────────────────────┐
+         ▼                    ▼                    ▼
+┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
+│ core/prime.js   │ │ physics/kuramoto│ │ core/hilbert.js │
+│                 │ │                 │ │                 │
+│ • Prime encoding│ │ • Oscillator    │ │ • PrimeState    │
+│ • Factorization │ │   dynamics      │ │ • Complex amps  │
+│ • Resonance     │ │ • Coupling      │ │ • Entropy       │
+└─────────────────┘ └─────────────────┘ └─────────────────┘
+```
+
+### Integration with Existing Modules
+
+| TinyAleph Module | Bioinformatics Use |
+|------------------|-------------------|
+| `core/prime.js` | Nucleotide/amino acid prime mapping |
+| `core/hilbert.js` | Sequence states in prime Hilbert space |
+| `core/resonance.js` | Binding affinity via golden ratio |
+| `physics/kuramoto.js` | Protein folding dynamics |
+| `physics/entropy.js` | Fitness/stability metrics |
+| `physics/sync-models.js` | Multi-domain protein coupling |
+
+---
+
+## 2. Prime Encoding Schemes
+
+### 2.1 Nucleotide Prime Basis
+
+```javascript
+const NUCLEOTIDE_PRIMES = {
+  'A': 7,   // Adenine (purine)
+  'T': 2,   // Thymine (pyrimidine)
+  'G': 11,  // Guanine (purine)
+  'C': 3,   // Cytosine (pyrimidine)
+  'U': 5,   // Uracil (RNA)
+};
+
+// Watson-Crick pairing: complementary bases have same prime product
+// A-T: 7*2 = 14, G-C: 11*3 = 33
+```
+
+### 2.2 Amino Acid Prime Basis
+
+```javascript
+const AMINO_ACID_PRIMES = {
+  // Hydrophobic (small primes)
+  'G': 23, 'A': 29, 'V': 31, 'L': 37, 'I': 41, 'M': 43,
+  // Aromatic
+  'F': 47, 'W': 53, 'Y': 59,
+  // Polar
+  'S': 61, 'T': 67, 'C': 71, 'N': 73, 'Q': 79,
+  // Charged
+  'K': 83, 'R': 89, 'H': 97, 'D': 101, 'E': 103,
+  // Special
+  'P': 107, '*': 109
+};
+```
+
+---
+
+## 3. Biological Transform Operators
+
+### 3.1 Central Dogma Pipeline
+
+```
+DNA ──[Transcription]──► RNA ──[Translation]──► Protein ──[Folding]──► Structure
+ │                        │                       │                      │
+ ▼                        ▼                       ▼                      ▼
+[2,3,7,11]          [3,5,7,11]           [23-109 range]         [Phase array]
+```
+
+### 3.2 Transform Summary
+
+| Transform | Input | Output | Entropy Change |
+|-----------|-------|--------|----------------|
+| Transcription | DNA primes | RNA primes | +0.01×len |
+| Translation | RNA primes | Protein primes | -codons×log₂(3) |
+| Folding | Protein primes | Phase array | →0 (minimized) |
+| Binding | 2 molecules | Affinity score | -ΔG/RT |
+
+---
+
+## 4. Molecular Dynamics via Oscillator Coupling
+
+### 4.1 Protein Folding as Kuramoto Synchronization
+
+Each amino acid residue becomes an oscillator with:
+- **Natural frequency**: `f(p) = 1 + log(p)/10` (from prime value)
+- **Coupling**: Contact propensity matrix based on:
+  - Prime resonance (golden ratio proximity)
+  - Hydrophobicity (smaller primes attract)
+  - Electrostatics (charged primes repel/attract)
+
+**Folded state** = High order parameter (synchronized oscillators)
+
+### 4.2 Binding as Multi-System Coupling
+
+Protein-ligand binding uses `MultiSystemCoupling`:
+- Receptor and ligand as separate oscillator banks
+- Cross-coupling from pairwise prime resonance
+- Docking score from inter-system coherence
+
+---
+
+## 5. BioinformaticsBackend Class
+
+### 5.1 Interface Implementation
+
+```javascript
+class BioinformaticsBackend extends Backend {
+  // Required by Backend interface
+  encode(input)              // Sequence string → prime array
+  decode(primes)             // Prime array → sequence string
+  primesToState(primes)      // Primes → Hypercomplex state
+  primesToFrequencies(primes)// Primes → oscillator frequencies
+  applyTransform(primes, t)  // Apply biological transform
+  getTransforms()            // List available transforms
+  getPrimes()                // Get biological prime set
+  
+  // Bioinformatics-specific methods
+  transcribe(dna)            // DNA → RNA
+  translate(rna)             // RNA → Protein
+  express(dna)               // DNA → Protein (full pipeline)
+  fold(protein)              // Protein → 3D structure
+  mutate(seq, mutation)      // Apply mutation
+  align(seq1, seq2)          // Sequence alignment
+  bindingAffinity(mol1, mol2)// Compute binding score
+}
+```
+
+### 5.2 Transform Registry
+
+```javascript
+const BIOINFORMATICS_TRANSFORMS = [
+  { type: 'transcription', name: 'DNA→RNA' },
+  { type: 'translation', name: 'RNA→Protein' },
+  { type: 'complement', name: 'DNA complement' },
+  { type: 'reverse_complement', name: 'Reverse complement' },
+  { type: 'fold', name: 'Protein folding' },
+  { type: 'mutation', mutationType: 'point', name: 'Point mutation' },
+  { type: 'mutation', mutationType: 'insertion', name: 'Insertion' },
+  { type: 'mutation', mutationType: 'deletion', name: 'Deletion' },
+];
+```
+
+---
+
+## 6. Usage Examples
+
+### 6.1 Basic Usage
+
+```javascript
+const { createEngine, BioinformaticsBackend } = require('@aleph-ai/tinyaleph');
+
+// Create bioinformatics engine
+const config = { dimension: 32 };
+const engine = createEngine('bioinformatics', config);
+
+// Encode and process DNA sequence
+const result = engine.run('ATGCGATCGATCG');
+
+console.log('Input primes:', result.inputPrimes);
+console.log('Entropy:', result.entropy);
+console.log('Coherence:', result.coherence);
+```
+
+### 6.2 Gene Expression
+
+```javascript
+const backend = new BioinformaticsBackend();
+
+// DNA sequence
+const dna = backend.encode('ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGA');
+
+// Express gene
+const rna = backend.transcribe(dna);
+const protein = backend.translate(rna);
+
+console.log('DNA primes:', dna);
+console.log('RNA primes:', rna);
+console.log('Protein primes:', protein);
+console.log('Protein sequence:', backend.decode(protein));
+```
+
+### 6.3 Protein Folding
+
+```javascript
+const backend = new BioinformaticsBackend();
+
+// Encode protein
+const proteinPrimes = backend.encode('MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH');
+
+// Fold protein
+const foldResult = backend.fold(proteinPrimes);
+
+console.log('Order parameter:', foldResult.orderParameter);
+console.log('Secondary structure:', foldResult.structure.map(s => s.secondaryStructure));
+console.log('Contacts:', foldResult.contacts.length);
+console.log('Free energy:', foldResult.foldingFreeEnergy);
+```
+
+### 6.4 Binding Affinity Screening
+
+```javascript
+const backend = new BioinformaticsBackend();
+const calculator = new BindingAffinityCalculator();
+
+// Target protein
+const target = backend.encode('MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQQIA');
+
+// Ligand library
+const ligands = [
+  { id: 'aspirin', primes: backend.encode('CCOC1=CC=CC=C1OC') },
+  { id: 'caffeine', primes: backend.encode('CN1C=NC2=C1C=NC=N2') },
+  { id: 'glucose', primes: backend.encode('OC1OC(CO)C(O)C(O)C1O') }
+];
+
+// Screen
+const results = calculator.screenLibrary(target, ligands);
+console.log('Top binder:', results[0].id, 'affinity:', results[0].affinity);
+```
+
+### 6.5 Mutation Analysis
+
+```javascript
+const backend = new BioinformaticsBackend();
+const mutator = new PointMutationOperator();
+
+// Original sequence
+const original = backend.encode('ATGGCCATTGTAATG');
+
+// Apply mutation at position 3
+const mutated = mutator.apply(original, 3, NUCLEOTIDE_PRIMES['T']);
+
+// Classify effect
+const effect = mutator.classify(original, mutated, 3);
+console.log('Mutation effect:', effect); // 'synonymous', 'missense', or 'nonsense'
+```
+
+### 6.6 Sequence Alignment via Oscillator Sync
+
+```javascript
+const backend = new BioinformaticsBackend();
+
+const seq1 = backend.encode('MVLSPADKTNVKAAW');
+const seq2 = backend.encode('MVHLTPEEKSAVTAL');
+
+const alignment = backend.align(seq1, seq2);
+
+console.log('Alignment coherence:', alignment.coherence);
+console.log('Phase alignment:', alignment.alignment);
+```
+
+---
+
+## 7. Integration with AlephEngine
+
+### 7.1 Engine Configuration
+
+```javascript
+function createEngine(backendType, config = {}) {
+  let backend;
+  
+  switch (backendType.toLowerCase()) {
+    case 'bioinformatics':
+    case 'bio':
+    case 'dna':
+      backend = new BioinformaticsBackend(config);
+      break;
+    // ... existing backends
+  }
+  
+  return new AlephEngine(backend, config.engineOptions || {});
+}
+```
+
+### 7.2 Field-Based Biological Computation
+
+The AlephEngine's field-based computation naturally models biological processes:
+
+1. **Excitation**: Input sequence excites oscillators (encode)
+2. **Evolution**: Kuramoto dynamics simulate molecular behavior
+3. **Sampling**: Coherent frames capture stable conformations
+4. **Decoding**: Convert oscillator state back to biological output
+
+This parallels how biological systems:
+- Store information in molecular structure
+- Evolve through thermodynamic processes
+- Settle into stable energy minima
+- Express functional outputs
+
+---
+
+## 8. Advanced Features
+
+### 8.1 Phylogenetic Analysis via Entanglement Graph
+
+```javascript
+// Use PrimeEntanglementGraph for sequence relationships
+const graph = new PrimeEntanglementGraph(allSequencePrimes);
+
+// Record co-evolution
+for (const [seq1, seq2] of sequencePairs) {
+  const primes1 = backend.encode(seq1);
+  const primes2 = backend.encode(seq2);
+  const similarity = backend.similarity(primes1, primes2);
+  graph.observe(primes1, primes2, similarity);
+}
+
+// Build phylogenetic tree
+const tree = graph.toAdjacencyMatrix(sequencePrimes);
+```
+
+### 8.2 Evolutionary Dynamics
+
+```javascript
+// Model evolution as entropy-driven process
+const evolution = new EntropyDrivenEvolution(
+  PrimeState.fromPrimes(genomePrimes),
+  {
+    lambda: 0.01,      // Mutation rate
+    rStable: 0.9       // Fitness threshold
+  }
+);
+
+// Evolve population
+const result = evolution.evolveUntilCollapse(10000);
+console.log('Generations:', result.steps);
+console.log('Final fitness:', result.probability);
+```
+
+### 8.3 Multi-Domain Protein Dynamics
+
+```javascript
+// Use SmallWorldKuramoto for allosteric effects
+const domain1 = proteinPrimes.slice(0, 100);
+const domain2 = proteinPrimes.slice(100, 200);
+const linker = proteinPrimes.slice(200, 220);
+
+const multiDomain = new SmallWorldKuramoto(
+  [...domain1, ...linker, ...domain2].map(p => primeToFrequency(p)),
+  4,    // neighbors
+  0.1,  // rewiring probability
+  0.3   // coupling
+);
+
+// Simulate allostery
+multiDomain.evolve(1000, 0.01);
+const allostericCoupling = multiDomain.smallWorldCoefficient();
+```
+
+---
+
+## 9. File Structure
+
+```
+backends/
+└── bioinformatics/
+    ├── index.js           # Main BioinformaticsBackend class
+    ├── encoding.js        # Nucleotide/AA prime mappings
+    ├── transcription.js   # DNA → RNA operator
+    ├── translation.js     # RNA → Protein operator
+    ├── mutation.js        # Mutation operators
+    ├── folding.js         # Kuramoto-based folding
+    ├── binding.js         # Affinity calculator
+    ├── alignment.js       # Sequence alignment
+    └── genetic-code.js    # Codon tables
+```
+
+---
+
+## 10. Testing Strategy
+
+```javascript
+// Unit tests for encoding
+test('nucleotide encoding', () => {
+  const backend = new BioinformaticsBackend();
+  expect(backend.encode('ATGC')).toEqual([7, 2, 11, 3]);
+});
+
+// Integration tests for expression
+test('gene expression pipeline', () => {
+  const backend = new BioinformaticsBackend();
+  const dna = backend.encode('ATGTTT'); // Met-Phe
+  const protein = backend.express(dna);
+  expect(backend.decode(protein)).toBe('MF');
+});
+
+// Folding convergence test
+test('folding converges', () => {
+  const backend = new BioinformaticsBackend();
+  const protein = backend.encode('MVLSPADKTNVKAAW');
+  const result = backend.fold(protein);
+  expect(result.orderParameter).toBeGreaterThan(0.8);
+});
+```
+
+---
+
+## 11. Performance Considerations
+
+| Operation | Complexity | Notes |
+|-----------|------------|-------|
+| Encoding | O(n) | Linear in sequence length |
+| Transcription | O(n) | Simple substitution |
+| Translation | O(n) | Codon lookup |
+| Folding | O(n²×s) | n residues, s steps |
+| Binding | O(m×n) | m×n pairwise interactions |
+| Alignment | O(m×n×s) | Multi-system coupling |
+
+For long sequences (>1000 residues), consider:
+- Sparse contact matrices
+- Hierarchical folding (domains first)
+- GPU acceleration for Kuramoto integration
+
+---
+
+## 12. Future Extensions
+
+### 12.1 CRISPR Editing Simulation
+Model guide RNA binding and Cas9 cleavage using resonance scoring.
+
+### 12.2 Metabolic Networks
+Extend to metabolic pathways as coupled reaction oscillators.
+
+### 12.3 Epigenetics
+Add methylation states as phase modifications to nucleotide oscillators.
+
+### 12.4 Drug Design
+Use inverse folding to design sequences with target binding properties.
+
+---
+
+## 13. Summary
+
+The BioinformaticsBackend provides a novel computational model for biological systems based on tinyaleph's prime-resonance framework:
+
+| Biological Concept | Prime-Resonance Analog |
+|--------------------|------------------------|
+| Genetic information | Prime signatures |
+| Base pairing | Prime product symmetry |
+| Gene expression | Entropy-reducing transforms |
+| Protein folding | Oscillator synchronization |
+| Molecular binding | Golden ratio resonance |
+| Evolution | Entropy-driven dynamics |
+
+This approach offers:
+1. **Unified framework** for sequence, structure, and dynamics
+2. **Physical grounding** via oscillator physics
+3. **Information-theoretic** metrics for biological function
+4. **Seamless integration** with existing tinyaleph infrastructure
+
+---
+
+*Design document version 1.0*
+*Author: TinyAleph Architecture Team*
+*Date: 2026-01-08*