Add comprehensive RR-RNN documentation with architecture diagrams and process flows

README.md

@@ -1,53 +1,232 @@
-# plingua
-The P-Lingua language for Membrane Computing
+# RR-PLingua: Relevance Realization Enhanced Membrane Computing
 
-P-Lingua is a comprehensive framework for membrane computing that provides a complete ecosystem for defining, parsing, simulating, and generating code for P-systems (membrane systems).
+**RR-PLingua** is an advanced membrane computing framework that integrates **Relevance Realization (RR)** dynamics with **OpenCog AtomSpace** symbolic reasoning, creating a unified platform for membrane computing with cognitive architectures.
 
-## 📚 Documentation
+## 🧠 RR-RNN: Relevance Realization with Recursive Neural Networks
+
+This implementation extends the traditional P-Lingua framework with four major Next Development Directions, creating a sophisticated system for symbolic-subsymbolic integration in membrane computing environments.
+
+### ✨ Key Features
+
+- **🔗 Advanced PLN Integration**: Probabilistic Logic Networks with RR pattern reasoning
+- **💬 Enhanced Scheme Interface**: Interactive REPL for system exploration and manipulation
+- **💾 Persistent AtomSpace**: JSON serialization and incremental learning capabilities
+- **🏗️ Multi-Level Integration**: Hierarchical membrane structures with cross-level emergence
+
+## 🎯 Implementation Summary
+
+### 1. Advanced PLN Integration ✅
+**File**: `include/pln_integration.hpp`
+
+- **PLN Truth Values**: Complete implementation with strength/confidence pairs
+- **Inference Rules**: 
+  - Deduction: A→B, A ⊢ B 
+  - Abduction: A→B, B ⊢ A (with reduced confidence)
+- **RR Pattern Implications**: Automatic generation of implications from high-coupling agent-arena relationships
+- **Full Inference Cycle**: Integrated PLN reasoning over membrane structures
 
-### [Comprehensive Architecture Documentation](docs/README.md)
-Detailed architectural insights with Mermaid diagrams covering:
-- **[System Architecture](docs/ARCHITECTURE.md)**: High-level design patterns and data flows
-- **[Component Deep Dive](docs/COMPONENTS.md)**: Internal architecture of parser, simulator, and generator
-- **[Usage Examples](docs/EXAMPLES.md)**: Practical demonstrations and integration guides
+### 2. Enhanced Scheme Interface ✅
+**File**: `include/scheme_interface.hpp`
 
-## Dependencies 
+- **Interactive REPL**: Full Scheme-style command evaluation
+- **Command Set**: 8+ commands for system exploration and manipulation
+- **Pattern Matching**: Query and analyze both RR and AtomSpace structures
+- **Real-time Updates**: Modify system state through Scheme commands
 
-* Linux OS (tested on Ubuntu 16.04 and Ubuntu 18.04)
-* GCC 4.9.0 or higher (with support for regex)
-* Flex
-* Bison
-* libboost-filesystem-dev 
-* libboost-program-options-dev
+### 3. Persistent AtomSpace ✅
+**File**: `include/persistent_atomspace.hpp`
 
-sudo apt-get install build-essential flex bison libboost-filesystem-dev libboost-program-options-dev 
+- **JSON Serialization**: Complete save/load for AtomSpace state
+- **RR Hypergraph Persistence**: Serialize all RR dynamics and structure
+- **Incremental Learning**: Merge new experiences with existing knowledge
+- **Memory Consolidation**: Remove low-confidence atoms to optimize storage
 
-## Compiling
+### 4. Multi-Level Integration ✅
+**Distributed across**: `relevance_realization.hpp`, `atomspace_integration.hpp`, test files
 
-* make grammar
-* make compiler
-* make simulator
-* sudo make install
+- **Hierarchical Structures**: Support for nested membrane architectures
+- **Cross-Level Emergence**: Detection of patterns spanning multiple hierarchy levels
+- **Temporal Reasoning**: Track relevance evolution over time
+- **Multi-Scale Dynamics**: Coordinated RR updates across system levels
 
-## Architecture Overview
+## 🏛️ Architecture Overview
 
 ```mermaid
 graph TD
-    A[P-Lingua Source] --> B[Parser]
-    B --> C[P-System Model]
-    C --> D[Simulator]
-    C --> E[Code Generator]
-    D --> F[Results]
-    E --> G[Generated Code]
+    subgraph "Traditional P-Lingua Core"
+        A[P-Lingua Source] --> B[Parser]
+        B --> C[P-System Model]
+        C --> D[Simulator]
+        C --> E[Code Generator]
+    end
 
-    style A fill:#e3f2fd
-    style C fill:#f3e5f5
-    style F fill:#e8f5e8
-    style G fill:#fff3e0
+    subgraph "RR Enhancement Layer"
+        F[RR Hypergraph] --> G[Relevance Dynamics]
+        G --> H[Agent-Arena-Relation Triad]
+        H --> I[Trialectic Co-constitution]
+    end
+
+    subgraph "AtomSpace Integration"
+        J[OpenCog AtomSpace] --> K[PLN Inference]
+        K --> L[Pattern Recognition]
+        L --> M[Symbolic Reasoning]
+    end
+
+    subgraph "Unified Architecture"
+        N[RR-AtomSpace Bridge]
+        O[Scheme Interface]
+        P[Persistent Storage]
+        Q[Multi-Level Coordination]
+    end
+
+    C --> F
+    F --> J
+    J --> N
+    N --> O
+    N --> P
+    N --> Q
+
+    style F fill:#e3f2fd
+    style J fill:#f3e5f5
+    style N fill:#e8f5e8
+    style O fill:#fff3e0
 ```
 
-The framework consists of three main components:
-- **Parser**: Transforms P-Lingua source into executable models
-- **Simulator**: Executes membrane computing simulations
-- **Generator**: Produces optimized C++ implementations
+## 🔄 RR Dynamics Process Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent as Agent Membrane
+    participant Arena as Arena Membrane
+    participant RR as RR Engine
+    participant AtomSpace as AtomSpace
+    participant PLN as PLN Engine
+
+    Agent->>RR: Update salience
+    Arena->>RR: Update affordances
+    RR->>RR: Compute trialectic dynamics
+    RR->>AtomSpace: Sync RR properties
+    AtomSpace->>PLN: Generate implications
+    PLN->>PLN: Perform inference cycle
+    PLN->>AtomSpace: Update truth values
+    AtomSpace->>RR: Feedback to RR dynamics
+    RR->>Agent: Update relevance gradient
+    RR->>Arena: Update coupling strength
+```
+
+## 🚀 Quick Start
+
+### Dependencies
+
+```bash
+sudo apt-get install build-essential flex bison libboost-filesystem-dev libboost-program-options-dev libfl-dev
+```
+
+### Build & Test
+
+```bash
+# Build traditional P-Lingua
+make grammar
+make compiler
+make simulator
+
+# Build RR-enhanced test programs
+g++ -I./include -std=c++11 -o test_rr_enhanced test_rr_enhanced.cpp
+g++ -I./include -std=c++11 -o test_next_directions test_next_directions.cpp
+g++ -I./include -std=c++11 -o demo_repl demo_repl.cpp
+
+# Run comprehensive demo
+./test_next_directions
+```
+
+### Interactive RR/AtomSpace REPL
+
+```bash
+./demo_repl
+```
+
+Available Scheme commands:
+```scheme
+(list-rr-nodes)           ; List all RR nodes with properties
+(list-atoms)              ; Show AtomSpace contents  
+(get-system-relevance)    ; Compute overall system relevance
+(run-pln-inference)       ; Execute PLN reasoning cycle
+(find-patterns)           ; Detect emergent patterns
+(get-salience node-ID)    ; Query node salience
+(update-salience node-ID VALUE) ; Modify node properties
+(find-atom "NAME")        ; Search atoms by name
+```
+
+## 📊 Performance Characteristics
+
+### RR Dynamics Complexity
+- **Trialectic Updates**: O(n) per node per timestep
+- **Coupling Computation**: O(n²) for agent-arena pairs
+- **Emergence Detection**: O(n·m) for n agents, m arenas
+
+### AtomSpace Integration
+- **RR→Atom Conversion**: O(n) for n RR nodes
+- **PLN Inference**: O(r·a) for r rules, a atoms
+- **Pattern Matching**: O(p·log(a)) for p patterns
+
+## 🔬 Research Applications
+
+### Cognitive Architecture Integration
+- **Symbolic-Subsymbolic Bridge**: RR provides the dynamic foundation for symbolic reasoning
+- **Emergent Pattern Recognition**: Multi-level emergence detection across membrane hierarchies
+- **Adaptive Learning**: Persistent storage enables incremental knowledge accumulation
+
+### Membrane Computing Enhancements
+- **Dynamic Rule Selection**: RR salience influences rule application priorities
+- **Adaptive Membrane Behavior**: Agent-arena coupling drives membrane evolution
+- **Hierarchical Organization**: Multi-level integration supports complex system architectures
+
+## 📚 Documentation
+
+### [Comprehensive RR-RNN Documentation](docs/README.md)
+Detailed technical documentation with diagrams covering:
+- **[RR-RNN Architecture](docs/ARCHITECTURE.md)**: Relevance Realization integration patterns
+- **[Component Deep Dive](docs/COMPONENTS.md)**: PLN, Scheme, and persistence systems
+- **[Usage Examples](docs/EXAMPLES.md)**: RR dynamics and AtomSpace integration demos
+
+### Core Implementation Files
+
+```
+include/
+├── relevance_realization.hpp    # RR framework with trialectic dynamics
+├── atomspace_integration.hpp    # RR-AtomSpace bridge
+├── pln_integration.hpp          # PLN inference engine
+├── scheme_interface.hpp         # Interactive Scheme REPL
+└── persistent_atomspace.hpp     # Serialization & persistence
+
+test_*.cpp                       # Comprehensive test suite
+demo_*.cpp                       # Interactive demonstrations
+```
+
+## 🎯 Future Extensions
+
+The implemented framework provides the foundation for:
+
+1. **Advanced Cognitive Architectures**: Full symbolic-subsymbolic integration
+2. **Distributed RR Systems**: Multi-agent relevance realization networks  
+3. **Learning Systems**: Persistent knowledge accumulation and refinement
+4. **Interactive Exploration**: Real-time system analysis and manipulation
+
+## 🤝 Contributing
+
+This RR-enhanced membrane computing framework represents a significant advancement toward unified cognitive architectures. Contributions are welcome in:
+
+- Enhanced RR dynamics algorithms
+- Additional PLN inference rules
+- Extended Scheme command sets
+- Multi-level emergence patterns
+- Performance optimizations
+
+## 📄 License
+
+Licensed under the same terms as the original P-Lingua framework.
+
+---
+
+*RR-PLingua successfully bridges dynamic self-organization (RR) and symbolic reasoning (AtomSpace/PLN), representing a significant advancement toward unified cognitive architectures.*
 

docs/ARCHITECTURE.md

@@ -1,39 +1,71 @@
-# P-Lingua Architecture Documentation
+# RR-Enhanced P-Lingua Architecture Documentation
 
 ## Overview
 
-P-Lingua is a comprehensive framework for membrane computing that provides a complete ecosystem for defining, parsing, simulating, and generating code for P-systems (membrane systems). This documentation provides detailed architectural insights with visual diagrams to facilitate understanding and contribution.
+**RR-PLingua** is a revolutionary enhancement of the traditional P-Lingua framework that integrates **Relevance Realization (RR)** dynamics with **OpenCog AtomSpace** symbolic reasoning. This creates a sophisticated platform for cognitive membrane computing that bridges symbolic and subsymbolic processing.
+
+The enhanced system provides four major architectural innovations:
+1. **PLN Integration** - Probabilistic Logic Networks for uncertain reasoning
+2. **Scheme Interface** - Interactive exploration and manipulation
+3. **Persistent Storage** - Knowledge accumulation and memory consolidation  
+4. **Multi-Level Integration** - Hierarchical emergence detection
 
 ## High-Level System Architecture
 
 ```mermaid
 graph TD
-    A[P-Lingua Source Files] --> B[Lexical Analyzer]
-    B --> C[Parser]
-    C --> D[Syntax Tree]
-    D --> E[Semantic Analyzer]
-    E --> F[P-System Model]
-    F --> G[Simulator Engine]
-    F --> H[Code Generator]
-    G --> I[Configuration Output]
-    H --> J[C++ Generated Code]
-
-    subgraph "Core Components"
-        K[Parser Module]
-        L[Simulator Module] 
-        M[Generator Module]
-        N[Serialization Module]
+    subgraph "Traditional P-Lingua Layer"
+        A[P-Lingua Source Files] --> B[Lexical Analyzer]
+        B --> C[Parser]
+        C --> D[Syntax Tree]
+        D --> E[Semantic Analyzer]
+        E --> F[P-System Model]
+        F --> G[Simulator Engine]
+        F --> H[Code Generator]
+        G --> I[Configuration Output]
+        H --> J[C++ Generated Code]
     end
 
-    C --> K
-    G --> L
-    H --> M
-    F --> N
+    subgraph "RR Enhancement Layer"
+        K[RR Hypergraph]
+        L[Trialectic Dynamics]
+        M[Agent-Arena-Relation]
+        N[Relevance Gradients]
+    end
 
-    style A fill:#e1f5fe
-    style F fill:#f3e5f5
-    style I fill:#e8f5e8
-    style J fill:#fff3e0
+    subgraph "AtomSpace Integration Layer"
+        O[OpenCog AtomSpace]
+        P[PLN Inference Engine]
+        Q[Truth Value Management]
+        R[Pattern Recognition]
+    end
+
+    subgraph "Interactive & Persistence Layer"
+        S[Scheme REPL Interface]
+        T[JSON Serialization]
+        U[Memory Consolidation]
+        V[Multi-Level Coordination]
+    end
+
+    F --> K
+    K --> L
+    L --> M
+    M --> N
+
+    K --> O
+    O --> P
+    P --> Q
+    Q --> R
+
+    O --> S
+    O --> T
+    T --> U
+    K --> V
+
+    style K fill:#e3f2fd
+    style O fill:#f3e5f5
+    style S fill:#e8f5e8
+    style V fill:#fff3e0
 ```
 
 ## Core Data Structures