@aleph-ai/tinyaleph 1.5.6 → 1.6.0

package/examples/crypto/05-content-hash.js

@@ -0,0 +1,263 @@
+/**
+ * @example Content-Addressable Storage
+ * @description Use content hashes as addresses for deduplication
+ * 
+ * Content-addressable storage uses the hash of content as its address:
+ * - Identical content always has the same address
+ * - Enables automatic deduplication
+ * - Used in Git, IPFS, and other systems
+ */
+
+const { CryptographicBackend } = require('../../modular');
+
+// ===========================================
+// SETUP
+// ===========================================
+
+const backend = new CryptographicBackend({ dimension: 32 });
+
+console.log('TinyAleph Content-Addressable Storage Example');
+console.log('=============================================\n');
+
+// ===========================================
+// CONTENT-ADDRESSABLE STORE
+// ===========================================
+
+function ContentStore() {
+    this.objects = {};
+    this.refs = {};
+}
+
+ContentStore.prototype.hash = function(content) {
+    return backend.hash(content, 32).toString('hex');
+};
+
+ContentStore.prototype.put = function(content) {
+    var hash = this.hash(content);
+    if (!this.objects[hash]) {
+        this.objects[hash] = content;
+        return { hash: hash, new: true };
+    }
+    return { hash: hash, new: false, deduplicated: true };
+};
+
+ContentStore.prototype.get = function(hash) {
+    return this.objects[hash];
+};
+
+ContentStore.prototype.has = function(hash) {
+    return !!this.objects[hash];
+};
+
+ContentStore.prototype.setRef = function(name, hash) {
+    this.refs[name] = hash;
+};
+
+ContentStore.prototype.getRef = function(name) {
+    return this.refs[name];
+};
+
+ContentStore.prototype.stats = function() {
+    return {
+        objectCount: Object.keys(this.objects).length,
+        refCount: Object.keys(this.refs).length,
+        totalSize: Object.values(this.objects).reduce(function(sum, obj) {
+            return sum + obj.length;
+        }, 0)
+    };
+};
+
+// ===========================================
+// BASIC USAGE
+// ===========================================
+
+console.log('Basic Content-Addressable Storage:');
+console.log('-'.repeat(50) + '\n');
+
+var store = new ContentStore();
+
+var content1 = 'Hello, World!';
+var content2 = 'Goodbye, World!';
+var content3 = 'Hello, World!';  // Duplicate
+
+var result1 = store.put(content1);
+var result2 = store.put(content2);
+var result3 = store.put(content3);
+
+console.log('Storing content:');
+console.log('  "' + content1 + '" -> ' + result1.hash.substring(0, 16) + '... (new: ' + result1.new + ')');
+console.log('  "' + content2 + '" -> ' + result2.hash.substring(0, 16) + '... (new: ' + result2.new + ')');
+console.log('  "' + content3 + '" -> ' + result3.hash.substring(0, 16) + '... (new: ' + result3.new + ', dedup: ' + result3.deduplicated + ')');
+
+console.log('\nRetrieving by hash:');
+console.log('  ' + result1.hash.substring(0, 16) + '... -> "' + store.get(result1.hash) + '"');
+
+// ===========================================
+// DEDUPLICATION
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Automatic Deduplication:');
+console.log('='.repeat(50) + '\n');
+
+var dedupStore = new ContentStore();
+
+// Simulate storing files with duplicates
+var files = [
+    { name: 'doc1.txt', content: 'This is document content.' },
+    { name: 'doc2.txt', content: 'Different document content.' },
+    { name: 'doc3.txt', content: 'This is document content.' },  // Duplicate of doc1
+    { name: 'doc4.txt', content: 'Another unique document.' },
+    { name: 'doc5.txt', content: 'This is document content.' }   // Duplicate of doc1
+];
+
+var fileRefs = {};
+var stats = { stored: 0, deduplicated: 0 };
+
+console.log('Storing files:\n');
+
+for (var i = 0; i < files.length; i++) {
+    var file = files[i];
+    var result = dedupStore.put(file.content);
+    fileRefs[file.name] = result.hash;
+    
+    if (result.new) {
+        stats.stored++;
+        console.log('  ' + file.name + ': STORED (new content)');
+    } else {
+        stats.deduplicated++;
+        console.log('  ' + file.name + ': DEDUPLICATED (content exists)');
+    }
+}
+
+console.log('\nDeduplication stats:');
+console.log('  Total files: ' + files.length);
+console.log('  Unique stored: ' + stats.stored);
+console.log('  Deduplicated: ' + stats.deduplicated);
+console.log('  Space saved: ' + (stats.deduplicated / files.length * 100).toFixed(0) + '%');
+
+// ===========================================
+// VERSIONED STORAGE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Version Control with Content Addressing:');
+console.log('='.repeat(50) + '\n');
+
+function VersionedDocument(store, name) {
+    this.store = store;
+    this.name = name;
+    this.versions = [];
+}
+
+VersionedDocument.prototype.update = function(content) {
+    var result = this.store.put(content);
+    this.versions.push({
+        hash: result.hash,
+        timestamp: new Date().toISOString(),
+        version: this.versions.length + 1
+    });
+    return result;
+};
+
+VersionedDocument.prototype.getVersion = function(version) {
+    var versionInfo = this.versions[version - 1];
+    if (!versionInfo) return null;
+    return {
+        content: this.store.get(versionInfo.hash),
+        ...versionInfo
+    };
+};
+
+VersionedDocument.prototype.latest = function() {
+    return this.getVersion(this.versions.length);
+};
+
+VersionedDocument.prototype.history = function() {
+    return this.versions;
+};
+
+var vStore = new ContentStore();
+var doc = new VersionedDocument(vStore, 'readme.md');
+
+console.log('Creating document versions:\n');
+
+doc.update('# Version 1\n\nInitial content.');
+doc.update('# Version 2\n\nAdded more details.');
+doc.update('# Version 3\n\nFinal version with all content.');
+
+console.log('Version history:');
+var history = doc.history();
+for (var i = 0; i < history.length; i++) {
+    var v = history[i];
+    console.log('  v' + v.version + ': ' + v.hash.substring(0, 16) + '...');
+}
+
+console.log('\nRetrieving specific versions:');
+var v1 = doc.getVersion(1);
+var v3 = doc.latest();
+console.log('  v1: "' + v1.content.substring(0, 25) + '..."');
+console.log('  v3: "' + v3.content.substring(0, 25) + '..."');
+
+// ===========================================
+// MERKLE TREE
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('Merkle Tree (Hash Tree):');
+console.log('='.repeat(50) + '\n');
+
+function buildMerkleTree(items) {
+    if (items.length === 0) return null;
+    
+    // Hash all leaves
+    var leaves = items.map(function(item) {
+        return backend.hash(item, 32).toString('hex');
+    });
+    
+    var tree = [leaves];
+    
+    // Build tree bottom-up
+    while (leaves.length > 1) {
+        var level = [];
+        for (var i = 0; i < leaves.length; i += 2) {
+            var left = leaves[i];
+            var right = leaves[i + 1] || left;  // Duplicate last if odd
+            var combined = backend.hash(left + right, 32).toString('hex');
+            level.push(combined);
+        }
+        tree.push(level);
+        leaves = level;
+    }
+    
+    return {
+        root: leaves[0],
+        tree: tree
+    };
+}
+
+var dataBlocks = ['Block A', 'Block B', 'Block C', 'Block D'];
+var merkle = buildMerkleTree(dataBlocks);
+
+console.log('Data blocks: ' + dataBlocks.join(', '));
+console.log('\nMerkle Tree:');
+console.log('  Root: ' + merkle.root.substring(0, 32) + '...');
+console.log('  Levels: ' + merkle.tree.length);
+
+for (var level = merkle.tree.length - 1; level >= 0; level--) {
+    var indent = '  '.repeat(merkle.tree.length - level);
+    console.log(indent + 'Level ' + level + ': ' + merkle.tree[level].length + ' nodes');
+}
+
+// ===========================================
+// KEY TAKEAWAYS
+// ===========================================
+
+console.log('\n' + '='.repeat(50));
+console.log('KEY TAKEAWAYS:');
+console.log('1. Hash of content becomes its address');
+console.log('2. Identical content always has same address');
+console.log('3. Automatic deduplication saves storage');
+console.log('4. Versions can coexist with shared content');
+console.log('5. Merkle trees enable efficient verification');
+console.log('6. Used in Git, IPFS, blockchains, and more');

package/examples/crypto/README.md

@@ -0,0 +1,99 @@
+# Cryptographic Examples
+
+This directory contains examples demonstrating TinyAleph's cryptographic capabilities.
+
+## Examples
+
+### 01-password-hash.js
+**Password Hashing** - Securely hash passwords with salt support and timing attack resistance.
+
+```bash
+node examples/crypto/01-password-hash.js
+```
+
+### 02-key-derivation.js
+**Key Derivation** - Derive strong cryptographic keys from passwords using configurable work factor.
+
+```bash
+node examples/crypto/02-key-derivation.js
+```
+
+### 03-hmac.js
+**HMAC (Message Authentication)** - Create and verify message authentication codes for API signing and webhooks.
+
+```bash
+node examples/crypto/03-hmac.js
+```
+
+### 04-file-integrity.js
+**File Integrity** - Verify file integrity using cryptographic hashes and manifest files.
+
+```bash
+node examples/crypto/04-file-integrity.js
+```
+
+### 05-content-hash.js
+**Content-Addressable Storage** - Use content hashes as addresses for automatic deduplication.
+
+```bash
+node examples/crypto/05-content-hash.js
+```
+
+## Key Concepts
+
+### Cryptographic Hashing
+One-way functions that produce fixed-size output from any input:
+- Deterministic: same input always produces same output
+- One-way: cannot reverse to get original input
+- Collision-resistant: hard to find two inputs with same output
+- Avalanche effect: small input changes cause large output changes
+
+### Key Derivation
+Creating strong cryptographic keys from potentially weak passwords:
+- Uses salt to prevent rainbow table attacks
+- Configurable iterations (work factor) for security/performance tradeoff
+- Produces keys of specified length for various algorithms
+
+### HMAC
+Combining a secret key with a message for authentication:
+- Verifies message integrity (not tampered)
+- Verifies message authenticity (from expected sender)
+- Uses a shared secret key known only to trusted parties
+
+### Content Addressing
+Using the hash of content as its address:
+- Identical content always has the same address
+- Enables automatic deduplication
+- Used in Git, IPFS, blockchains, and more
+
+## Usage Pattern
+
+```javascript
+const { CryptographicBackend } = require('../../modular');
+
+// Create backend
+const backend = new CryptographicBackend({ dimension: 32 });
+
+// Hash data
+const hash = backend.hash('input data', 32);
+console.log(hash.toString('hex'));
+
+// Derive key
+const key = backend.deriveKey('password', 'salt', 32, 10000);
+console.log(key.toString('hex'));
+```
+
+## Security Considerations
+
+1. **Salt passwords** - Always use unique salts per user/purpose
+2. **Constant-time comparison** - Prevent timing attacks when verifying
+3. **Increase iterations** - Higher work factor = harder to brute force
+4. **Keep keys secret** - Never expose secret keys in logs or responses
+5. **Use appropriate key lengths** - 256 bits (32 bytes) for modern security
+
+## Next Steps
+
+After understanding cryptographic operations, explore:
+- `../semantic/` - Semantic text processing
+- `../scientific/` - Quantum computing simulation
+- `../apps/` - Full application examples

package/examples/demo-modular.js

@@ -0,0 +1,223 @@
+/**
+ * TinyAleph Modular Demo
+ * 
+ * Demonstrates the three backend types:
+ * 1. Semantic - Natural language processing
+ * 2. Cryptographic - Hashing and key derivation
+ * 3. Scientific - Quantum simulation
+ */
+
+const {
+  createEngine,
+  SemanticBackend,
+  CryptographicBackend,
+  ScientificBackend,
+  AlephEngine,
+  hash,
+  deriveKey
+} = require('../modular');
+
+console.log('╔═══════════════════════════════════════════════════════════════╗');
+console.log('║         TinyAleph Modular Architecture Demo                  ║');
+console.log('╚═══════════════════════════════════════════════════════════════╝\n');
+
+// ============================================
+// 1. SEMANTIC COMPUTING
+// ============================================
+console.log('┌───────────────────────────────────────────────────────────────┐');
+console.log('│  SEMANTIC BACKEND - Natural Language Understanding           │');
+console.log('└───────────────────────────────────────────────────────────────┘\n');
+
+const semanticConfig = {
+  dimension: 16,
+  vocabulary: {
+    'love': [2, 3, 5],
+    'truth': [7, 11, 13],
+    'wisdom': [2, 7, 11],
+    'knowledge': [3, 5, 7],
+    'beauty': [2, 5, 11],
+    'justice': [3, 7, 13],
+    'freedom': [5, 11, 17],
+    'peace': [2, 3, 7]
+  },
+  ontology: {
+    2: 'existence',
+    3: 'unity',
+    5: 'form',
+    7: 'logos',
+    11: 'psyche',
+    13: 'telos',
+    17: 'dynamis'
+  },
+  transforms: [
+    { n: 'synthesis', q: [2, 3], r: [5] },
+    { n: 'analysis', q: [5], r: [2, 3] },
+    { n: 'transcend', q: [2, 3, 5], r: [7, 11] }
+  ]
+};
+
+const semanticEngine = createEngine('semantic', semanticConfig);
+
+console.log('Processing: "love and truth lead to wisdom"\n');
+const semanticResult = semanticEngine.run('love and truth lead to wisdom');
+
+console.log(`  Input primes:  [${semanticResult.inputPrimes.slice(0, 8).join(', ')}...]`);
+console.log(`  Output:        "${semanticResult.output}"`);
+console.log(`  Entropy:       ${semanticResult.entropy.toFixed(3)}`);
+console.log(`  Coherence:     ${semanticResult.coherence.toFixed(3)}`);
+console.log(`  Stability:     ${semanticResult.stability}`);
+
+if (semanticResult.steps.length > 0) {
+  console.log('\n  Reasoning steps:');
+  for (const step of semanticResult.steps) {
+    console.log(`    ${step.step}. ${step.transform} (ΔH = -${step.entropyDrop.toFixed(3)})`);
+  }
+}
+
+// ============================================
+// 2. CRYPTOGRAPHIC APPLICATIONS
+// ============================================
+console.log('\n┌───────────────────────────────────────────────────────────────┐');
+console.log('│  CRYPTOGRAPHIC BACKEND - Hashing & Key Derivation            │');
+console.log('└───────────────────────────────────────────────────────────────┘\n');
+
+const cryptoBackend = new CryptographicBackend({ dimension: 32 });
+
+// Hashing demonstration
+console.log('Hashing demonstration:');
+const message1 = 'Hello, World!';
+const message2 = 'Hello, World?';
+
+const hash1 = cryptoBackend.hash(message1);
+const hash2 = cryptoBackend.hash(message2);
+
+console.log(`  Input 1: "${message1}"`);
+console.log(`  Hash 1:  ${hash1.toString('hex').slice(0, 32)}...`);
+console.log(`  Input 2: "${message2}"`);
+console.log(`  Hash 2:  ${hash2.toString('hex').slice(0, 32)}...`);
+console.log(`  Different: ${!hash1.equals(hash2)}`);
+
+// Key derivation
+console.log('\nKey derivation (PBKDF-like):');
+const password = 'my-secret-password';
+const salt = 'random-salt-value';
+const key = cryptoBackend.deriveKey(password, salt, 32, 1000);
+console.log(`  Password: "${password}"`);
+console.log(`  Salt:     "${salt}"`);
+console.log(`  Key:      ${key.toString('hex').slice(0, 32)}...`);
+
+// HMAC
+console.log('\nHMAC computation:');
+const hmacKey = 'secret-key';
+const hmacMsg = 'authenticate this message';
+const hmac = cryptoBackend.hmac(hmacKey, hmacMsg);
+console.log(`  Key:     "${hmacKey}"`);
+console.log(`  Message: "${hmacMsg}"`);
+console.log(`  HMAC:    ${hmac.toString('hex').slice(0, 32)}...`);
+
+// ============================================
+// 3. SCIENTIFIC COMPUTING
+// ============================================
+console.log('\n┌───────────────────────────────────────────────────────────────┐');
+console.log('│  SCIENTIFIC BACKEND - Quantum Simulation                     │');
+console.log('└───────────────────────────────────────────────────────────────┘\n');
+
+const scientificBackend = new ScientificBackend({ dimension: 16 });
+
+// Quantum state manipulation
+console.log('Quantum state encoding:');
+console.log(`  |0⟩ encodes to: [${scientificBackend.encode('|0⟩').join(', ')}]`);
+console.log(`  |1⟩ encodes to: [${scientificBackend.encode('|1⟩').join(', ')}]`);
+console.log(`  |+⟩ encodes to: [${scientificBackend.encode('|+⟩').join(', ')}]`);
+console.log(`  |Φ+⟩ (Bell) encodes to: [${scientificBackend.createEntangledPair('Φ+').join(', ')}]`);
+
+// Quantum gates
+console.log('\nQuantum gate application:');
+const qubit0 = [2];  // |0⟩
+console.log(`  Initial: |0⟩ = [${qubit0.join(', ')}]`);
+
+const afterX = scientificBackend.applyGate(qubit0, 'X');
+console.log(`  After X gate: [${afterX.join(', ')}] → ${scientificBackend.decode(afterX)}`);
+
+const afterH = scientificBackend.applyGate(qubit0, 'H');
+console.log(`  After H gate: [${afterH.join(', ')}] → ${scientificBackend.decode(afterH)}`);
+
+// Measurement
+console.log('\nQuantum measurement (10 samples from |+⟩ state):');
+const plusState = scientificBackend.primesToState([2, 3]);
+const outcomes = { '|0⟩': 0, '|1⟩': 0 };
+for (let i = 0; i < 10; i++) {
+  const result = scientificBackend.measure(plusState);
+  outcomes[result.state]++;
+}
+console.log(`  |0⟩ outcomes: ${outcomes['|0⟩']}`);
+console.log(`  |1⟩ outcomes: ${outcomes['|1⟩']}`);
+
+// Particle interaction
+console.log('\nParticle interaction simulation:');
+const electron = [11];  // electron prime
+const positron = [13];  // positron prime
+const interaction = scientificBackend.interact(electron, positron, 'electromagnetic');
+console.log(`  Particles: electron [${electron}] + positron [${positron}]`);
+console.log(`  Interaction: ${interaction.interaction}`);
+console.log(`  Conserved quantity: ${interaction.conserved}`);
+
+// ============================================
+// 4. BACKEND SWITCHING AT RUNTIME
+// ============================================
+console.log('\n┌───────────────────────────────────────────────────────────────┐');
+console.log('│  RUNTIME BACKEND SWITCHING                                   │');
+console.log('└───────────────────────────────────────────────────────────────┘\n');
+
+const engine = createEngine('semantic', semanticConfig);
+console.log(`Starting backend: ${engine.getBackendInfo().name}`);
+
+engine.setBackend(new CryptographicBackend({ dimension: 32 }));
+console.log(`Switched to:      ${engine.getBackendInfo().name}`);
+
+engine.setBackend(new ScientificBackend({ dimension: 16 }));
+console.log(`Switched to:      ${engine.getBackendInfo().name}`);
+
+// ============================================
+// 5. PHYSICS ENGINE DEMONSTRATION
+// ============================================
+console.log('\n┌───────────────────────────────────────────────────────────────┐');
+console.log('│  PHYSICS ENGINE - Oscillator Dynamics                        │');
+console.log('└───────────────────────────────────────────────────────────────┘\n');
+
+const physicsEngine = createEngine('semantic', semanticConfig);
+physicsEngine.run('test input to excite oscillators');
+
+console.log('Evolving system for 20 time steps:');
+const evolution = physicsEngine.evolve(20);
+
+console.log('\n  Step | Entropy | Order | Stability');
+console.log('  -----+---------+-------+----------');
+for (let i = 0; i < evolution.length; i += 4) {
+  const e = evolution[i];
+  console.log(`   ${String(e.step).padStart(2)}  |  ${e.entropy.toFixed(3)}  | ${e.orderParameter.toFixed(3)} | ${e.stability}`);
+}
+
+const finalState = physicsEngine.getPhysicsState();
+console.log(`\n  Final Lyapunov exponent: ${finalState.lyapunov.toFixed(4)}`);
+console.log(`  Final coupling strength: ${finalState.coupling.toFixed(3)}`);
+console.log(`  Collapse probability:    ${finalState.collapseProbability.toFixed(3)}`);
+
+// ============================================
+// SUMMARY
+// ============================================
+console.log('\n╔═══════════════════════════════════════════════════════════════╗');
+console.log('║                     Demo Complete                             ║');
+console.log('╠═══════════════════════════════════════════════════════════════╣');
+console.log('║  Backends demonstrated:                                       ║');
+console.log('║    ✓ SemanticBackend     - NLP, concept mapping               ║');
+console.log('║    ✓ CryptographicBackend - hash, PBKDF, HMAC                 ║');
+console.log('║    ✓ ScientificBackend   - quantum gates, measurement         ║');
+console.log('║                                                               ║');
+console.log('║  Features shown:                                              ║');
+console.log('║    ✓ Unified AlephEngine with backend-agnostic API            ║');
+console.log('║    ✓ Runtime backend switching                                ║');
+console.log('║    ✓ Kuramoto oscillator physics simulation                   ║');
+console.log('║    ✓ Lyapunov stability analysis                              ║');
+console.log('║    ✓ Entropy-minimizing reasoning                             ║');
+console.log('╚═══════════════════════════════════════════════════════════════╝\n');