From 133a29d9bcad1b6154465e9b199ee812c3ccb466 Mon Sep 17 00:00:00 2001 From: naresrac Date: Sat, 15 Nov 2025 09:54:50 +0530 Subject: [PATCH 1/4] Add comprehensive overview for BrainSim III Added comprehensive overview documentation for BrainSim III, detailing its architecture, unique features, reasoning capabilities, and implementation strategies. --- user_docs/00_overview.md | 589 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 589 insertions(+) create mode 100644 user_docs/00_overview.md diff --git a/user_docs/00_overview.md b/user_docs/00_overview.md new file mode 100644 index 0000000..000d935 --- /dev/null +++ b/user_docs/00_overview.md @@ -0,0 +1,589 @@ +# BrainSim III: Comprehensive Overview + +## Introduction + +**BrainSim III** is a knowledge representation system designed for Common Sense AI, built around the **Universal Knowledge Store (UKS)**—a custom in-memory graph database. The system represents knowledge as interconnected concepts (Things) linked by semantic relationships, supporting inheritance, conditional logic, and neural-inspired mechanisms. + +## What Makes BrainSim III Unique? + +### 1. Structural Intelligence, Not Symbolic Programming + +Unlike traditional AI that uses hard-coded rules and class definitions, BrainSim III represents all knowledge through **graph structure**: + +``` +Traditional AI: +class Dog(Animal): + legs = 4 + def bark(self): return "woof" + +BrainSim III: +[Dog] --[is-a]--> [Animal] + --[has]--> [Leg] (count: 4) + --[can]--> [Bark] +``` + +**Advantages**: +- No code changes needed to add knowledge +- Learning happens through structure modification +- Gradual confidence through weighted relationships +- Natural exception handling through conditional clauses + +### 2. True Reasoning vs. Pattern Matching + +While Large Language Models (LLMs) perform pattern matching on training data, BrainSim III performs **logical reasoning** through graph traversal: + +| LLM Approach | BrainSim III Approach | +|--------------|----------------------| +| "Dogs typically have 4 legs" (statistical) | `[Dog] --[has]--> [Leg] (weight: 0.95)` | +| Cannot explain reasoning | Traceable path: Dog → is-a → Animal → has → Leg | +| Hallucinates when uncertain | Returns weighted confidence or "unknown" | +| Fixed at training time | Dynamically updated during operation | + +### 3. Hybrid Human-Like Reasoning + +The system combines: +- **Deductive reasoning**: Following inheritance chains +- **Inductive reasoning**: Bubbling common attributes to generalizations +- **Abductive reasoning**: Causal explanations via BECAUSE clauses +- **Analogical reasoning**: Finding common patterns across structures + +## Core Architecture + +### The Graph Foundation + +``` +Thing (Node) + │ + ├── Label: Unique identifier + ├── V: Arbitrary attached data + ├── Relationships: Outgoing edges (outputs) + ├── RelationshipsFrom: Incoming edges (inputs) + ├── Parents/Children: Inheritance hierarchy + └── UseCount/LastFiredTime: Usage tracking + +Relationship (Edge) + │ + ├── Source: Thing + ├── RelType: Thing (self-referential!) + ├── Target: Thing + ├── Weight: Confidence (0-1) + ├── Hits/Misses: Usage statistics + ├── Clauses: Conditional logic (IF/BECAUSE/UNLESS) + └── TimeToLive: Transience support + +Clause (Meta-Edge) + │ + ├── ClauseType: Thing ("IF", "BECAUSE", etc.) + └── Clause: Relationship (relationships between relationships!) +``` + +**Implication**: Things are unambiguous concepts with clear labels, implying cannot work with abstract concepts? And yet unclear concepts (temporal emerging) in the network? + +### Self-Referential Type System + +**Key Innovation**: Relationship types are themselves Things in the graph. + +``` +[is-a] --[is-a]--> [RelationshipType] + --[hasProperty]--> [isTransitive] + +[has] --[is-a]--> [RelationshipType] + --[hasProperty]--> [isInheritable] + +[color] --[is-a]--> [Attribute] + --[hasProperty]--> [isExclusive] +``` + +This eliminates the need for schema definitions and enables runtime type creation. + +**Implication**: Does this cause too much connection overload for these types? + +## Key Concepts and Their Implementations + +### 1. Knowledge Representation + +**Document**: [01_knowledge_representation.md](01_knowledge_representation.md) + +**Core Principles**: +- **Information Singularity**: Each concept exists once, identified by unique label +- **Structure = Facts**: Knowledge emerges from graph structure, not node data +- **Directionality**: Relationships are directed but maintain bidirectional navigation +- **Distributed Representation**: Information spreads across edges, providing resilience + +**Key Components**: +- Thing: Universal node abstraction (580 lines, [Thing.cs](../UKS/Thing.cs)) +- Relationship: Weighted semantic edge (396 lines, [Relationship.cs](../UKS/Relationship.cs)) +- Clause: Meta-relationship for conditional logic +- ThingLabels: Hash table for O(1) lookup + +### 2. Inheritance and Recursion + +**Document**: [02_inheritance_and_recursion.md](02_inheritance_and_recursion.md) + +**Mechanisms**: +- **IS-A relationships**: Build taxonomic hierarchies (DAG structure) +- **Multiple inheritance**: Things can have multiple parents +- **Attribute bubbling**: Common child attributes generalize upward +- **Redundancy removal**: Clean up duplicate inherited properties +- **Dynamic class creation**: Auto-generate intermediate classes for patterns +- **Exception handling**: Override inherited attributes with higher-weight direct ones + +**Key Algorithms**: +- `FollowTransitiveRelationships()`: Breadth-first ancestor/descendent traversal +- `RelationshipTree()`: Collect relationships including inherited +- `BubbleChildAttributes()`: Bottom-up generalization (ModuleAttributeBubble) +- `RemoveRedundantAttributes()`: Top-down cleanup (ModuleRemoveRedundancy) + +### 3. Conditional and Compound Logic + +**Document**: [03_conditional_compound_logic.md](03_conditional_compound_logic.md) + +**Clause Types**: +- **IF**: Conditional prerequisite (creates instances to preserve universals) +- **BECAUSE**: Causal explanation +- **UNLESS**: Exception handling +- **WHILE**: Temporal co-occurrence +- **THEN**: Sequential consequence + +**Logical Patterns**: +- **Conjunctive (AND)**: Multiple `requires` relationships +- **Disjunctive (OR)**: Multiple `achieved-by` relationships +- **Nested conditionals**: Clauses on clauses (recursive depth) +- **Temporal sequences**: Action chains with TTL +- **Spatial/social context**: Location and relationship-dependent truth +- **Affective causality**: Events cause emotional states + +**Temporal Support**: +- `TimeToLive`: Relationship expiration for working memory +- Background timer: 1-second tick removes expired relationships +- Transient relationships: Track temporary associations + +### 4. Neural Concepts and Resource Management + +**Document**: [04_neural_concepts_resource_management.md](04_neural_concepts_resource_management.md) + +**Neural-Inspired Mechanisms**: +- **Sparse coding**: Unique labels ensure singular representation (ThingLabels hash) +- **Lateral inhibition**: Exclusive properties create winner-take-all competition +- **Gating**: IF/UNLESS clauses and weight thresholds control information flow +- **In/Out neurons**: Relationships (outputs) vs RelationshipsFrom (inputs) +- **Cortical columns**: Hierarchical Thing groupings with shared inheritance +- **Instance selection**: Dynamic column allocation with auto-numbering + +**Resource Tracking**: +- `useCount`: Access frequency per Thing +- `lastFiredTime`: Last activation timestamp +- `hits/misses`: Relationship usage statistics +- Computed confidence: `Value = Hits / Misses` + +**Resilience**: +- Multiple inheritance paths provide redundancy +- Distributed representation survives node loss +- Relationship backup: Same fact represented multiple ways + +## Module System: Intelligent Agents + +### Agent Architecture + +Modules are autonomous agents that run every 100ms, reading and modifying the UKS. + +**Base Class**: [ModuleBase.cs](../BrainSimulator/Modules/ModuleBase.cs) + +```csharp +public abstract class ModuleBase +{ + public abstract void Fire(); // Called every cycle + public abstract void Initialize(); // One-time setup + + protected UKS theUKS; // Shared knowledge store + public bool isEnabled; // On/off switch +} +``` + +### Key Agent Modules + +**1. ModuleAttributeBubble** ([source](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs)) +- **Purpose**: Bottom-up generalization +- **Algorithm**: Count child attributes, bubble if >50% have it +- **Example**: 4 dogs all have tails → bubble to Dog class +- **Timer**: Runs every 10 seconds on background thread + +**2. ModuleRemoveRedundancy** ([source](../BrainSimulator/Modules/Agents/ModuleRemoveRedundancy.cs)) +- **Purpose**: Clean up inherited duplicates +- **Algorithm**: Remove child relationships that exist in parent with high weight +- **Example**: Dog has tail (0.95) → remove from Fido (redundant) + +**3. ModuleClassCreate** ([source](../BrainSimulator/Modules/Agents/ModuleClassCreate.cs)) +- **Purpose**: Auto-create intermediate classes +- **Algorithm**: Find attribute clusters, create subclass for each +- **Example**: 3+ red birds → create "Bird.has.color.Red" subclass + +**4. ModuleUKS** (Browser/Editor) +- **Purpose**: Visualize and manually edit UKS +- **Features**: Tree view, relationship editing, search + +**5. ModuleVision** (Perception) +- **Purpose**: Process images and create mental models +- **Features**: Corner detection, arc recognition, spatial relationships + +### Agent Coordination + +``` +Main Loop (100ms cycle): +├─ ModuleAttributeBubble: Generalizing common patterns +├─ ModuleRemoveRedundancy: Cleaning up redundancies +├─ ModuleClassCreate: Creating intermediate classes +├─ ModuleVision: Processing sensory input +└─ ModuleUKSStatement: Adding new knowledge +``` + +Agents cooperate through shared UKS but run independently. + +## Implementation Details + +### Technology Stack + +- **Language**: C# 8.0 +- **Framework**: .NET 8.0 +- **UI**: WPF (Windows Presentation Foundation) +- **Graph Storage**: Custom in-memory (up to 1TB capacity) +- **Serialization**: XML (SThing/SRelationship structures) +- **Python Integration**: Python.Runtime for mixed modules + +### Performance Characteristics + +**From stress tests and documentation**: +- **Throughput**: 100,000 relationships/second +- **Latency**: Sub-millisecond lookups via hash table +- **Capacity**: Scales to millions of Things +- **Cycle Time**: 100ms per agent execution cycle +- **TTL Cleanup**: 1-second granularity for transient relationships + +### File Organization + +``` +BrainSimIII/ +├── UKS/ (Core library) +│ ├── Thing.cs (580 lines) +│ ├── Relationship.cs (396 lines) +│ ├── UKS.cs (628 lines) +│ ├── UKS.Query.cs (513 lines) +│ ├── UKS.Statement.cs (335 lines) +│ ├── UKS.File.cs (539 lines) +│ └── ThingLabels.cs (79 lines) +├── BrainSimulator/ (Main application) +│ ├── Modules/ +│ │ ├── ModuleBase.cs +│ │ ├── Agents/ (15+ agent modules) +│ │ └── Vision/ (Perception modules) +│ ├── MainWindow.xaml.cs (353 lines) +│ └── ModuleHandler.cs (284 lines) +└── DocsSource/ (40+ markdown documentation files) +``` + +## Comparison: BrainSim III vs. Other Approaches + +### vs. Traditional Knowledge Graphs (Neo4j, RDF) + +| Feature | Neo4j/RDF | BrainSim III | +|---------|-----------|--------------| +| **Schema** | Fixed schema | Self-referential, no schema | +| **Reasoning** | Cypher queries | Transitive traversal + clauses | +| **Learning** | Manual updates | Autonomous agents modify structure | +| **Confidence** | Binary true/false | Weighted relationships (0-1) | +| **Temporal** | Versioning | Built-in TTL mechanism | +| **Inheritance** | Limited | Full multiple inheritance + bubbling | + +### vs. Neural Networks (PyTorch) + +| Feature | Neural Networks | BrainSim III | +|---------|----------------|--------------| +| **Representation** | Distributed embeddings | Explicit graph | +| **Interpretability** | Black box | Fully traceable | +| **Symbolic reasoning** | Poor | Native | +| **Learning** | Gradient descent | Structure modification + weights | +| **Memory** | Compressed in weights | Explicit storage | +| **Generalization** | Interpolation | Inheritance + transitive properties | + +### vs. Large Language Models (GPT, BERT) + +| Feature | LLMs | BrainSim III | +|---------|------|--------------| +| **Knowledge source** | Training corpus | Explicit encoding | +| **Reasoning** | Pattern matching | Logical traversal | +| **Explainability** | None (black box) | Full path tracing | +| **Updates** | Retraining required | Real-time modification | +| **Certainty** | Confidence scores (unreliable) | Weight-based (transparent) | +| **Context** | Token window | Graph structure | + +### vs. Prolog/Logic Programming + +| Feature | Prolog | BrainSim III | +|---------|--------|--------------| +| **Representation** | Horn clauses | Graph relationships | +| **Uncertainty** | Binary | Weighted confidence | +| **Learning** | Manual rule addition | Autonomous agents | +| **Temporal** | External timestamps | Built-in TTL | +| **Exceptions** | Cut operator | Weight + exclusivity | + +## Translating to PyTorch/PyTorch Geometric + +### Recommended Hybrid Approach + +**Preserve the best of both worlds**: + +1. **Explicit graph structure** (NetworkX or PyG Data) + - Maintain Things, Relationships, Clauses as graph + - Enable traceable reasoning + - Support symbolic operations + +2. **Neural embeddings** (PyTorch) + - Learn Thing representations + - Predict relationship weights + - Score query relevance + +3. **GNN for propagation** (PyTorch Geometric) + - Message passing for attribute inheritance + - Attention for lateral inhibition + - Gating networks for conditional logic + +### Architecture Sketch + +```python +import torch +import networkx as nx +from torch_geometric.nn import GATConv, GCNConv + +class HybridUKS: + def __init__(self): + # Explicit structure + self.graph = nx.DiGraph() + self.thing_labels = {} # Hash table for O(1) lookup + + # Neural components + self.thing_encoder = ThingEncoder(dim=128) + self.relation_encoder = RelationEncoder(dim=64) + self.gnn = UKS_GNN(in_channels=128, out_channels=128) + self.clause_evaluator = ClauseGNN(dim=128) + + def add_thing(self, label, parent=None): + # Explicit structure + self.graph.add_node(label, embedding=None) + self.thing_labels[label.lower()] = label + + # Neural embedding + embedding = self.thing_encoder.encode(label) + self.graph.nodes[label]['embedding'] = embedding + + if parent: + self.add_relationship(label, "is-a", parent) + + def add_relationship(self, source, reltype, target, weight=1.0): + self.graph.add_edge(source, target, + reltype=reltype, + weight=weight, + hits=0, misses=0) + + def query(self, source, reltype, use_neural=True): + if use_neural: + # Neural query ranking + return self.neural_query(source, reltype) + else: + # Symbolic traversal + return self.symbolic_query(source, reltype) + + def symbolic_query(self, source, reltype): + """Traditional graph traversal""" + results = [] + # Direct relationships + for neighbor in self.graph.successors(source): + edge_data = self.graph[source][neighbor] + if edge_data.get('reltype') == reltype: + results.append((neighbor, edge_data['weight'])) + + # Inherited relationships + ancestors = self.get_ancestors(source) + for ancestor in ancestors: + for neighbor in self.graph.successors(ancestor): + edge_data = self.graph[ancestor][neighbor] + if edge_data.get('reltype') == reltype: + results.append((neighbor, edge_data['weight'] * 0.9)) + + return sorted(results, key=lambda x: -x[1]) + + def neural_query(self, source, reltype): + """Neural ranking of candidates""" + # Get candidates via symbolic query + candidates = self.symbolic_query(source, reltype) + + # Re-rank using GNN + pyg_data = self.to_pyg_data() + node_embeddings = self.gnn(pyg_data.x, pyg_data.edge_index) + + source_idx = self.get_node_index(source) + source_emb = node_embeddings[source_idx] + reltype_emb = self.relation_encoder.encode(reltype) + + scores = [] + for candidate, weight in candidates: + candidate_idx = self.get_node_index(candidate) + candidate_emb = node_embeddings[candidate_idx] + + # Score: cosine similarity of (source + relation) to target + query_emb = source_emb + reltype_emb + score = F.cosine_similarity(query_emb, candidate_emb) + scores.append((candidate, score.item())) + + return sorted(scores, key=lambda x: -x[1]) +``` + +### Key Translation Strategies + +**1. Preserve Interpretability** +```python +# Store explicit relationships +self.graph.add_edge(source, target, reltype=reltype) + +# But also learn embeddings +self.embeddings[source] = neural_encoder(source) +``` + +**2. Implement Inheritance in GNN** +```python +class InheritanceGNN(MessagePassing): + def forward(self, x, edge_index, edge_type): + # Separate is-a edges from others + is_a_mask = (edge_type == IS_A_TYPE) + x_inherited = self.propagate(edge_index[:, is_a_mask], x=x) + return x + x_inherited # Combine direct + inherited +``` + +**3. Neural Clause Evaluation** +```python +class ClauseEvaluator(nn.Module): + def forward(self, rel1_emb, clause_type_emb, rel2_emb): + # IF clause: gate rel1 by rel2 + combined = torch.cat([rel1_emb, clause_type_emb, rel2_emb]) + gate = torch.sigmoid(self.gate_network(combined)) + return gate * rel1_emb +``` + +**4. Temporal Graph with TTL** +```python +class TemporalEdge: + def __init__(self, source, target, reltype, ttl=None): + self.timestamp = time.time() + self.ttl = ttl + + def is_expired(self): + if self.ttl is None: + return False + return time.time() - self.timestamp > self.ttl +``` + +## Getting Started with BrainSim III Concepts + +### Step 1: Understand the Core Abstractions + +Start with [01_knowledge_representation.md](01_knowledge_representation.md): +- Thing, Relationship, Clause +- Self-referential type system +- Weight-based confidence + +### Step 2: Learn Inheritance Mechanisms + +Read [02_inheritance_and_recursion.md](02_inheritance_and_recursion.md): +- IS-A relationships +- Attribute bubbling +- Multiple inheritance +- Dynamic class creation + +### Step 3: Master Conditional Logic + +Study [03_conditional_compound_logic.md](03_conditional_compound_logic.md): +- IF/BECAUSE/UNLESS clauses +- Temporal sequences +- Nested conditionals +- Working memory via TTL + +### Step 4: Explore Neural Concepts + +Review [04_neural_concepts_resource_management.md](04_neural_concepts_resource_management.md): +- Sparse coding +- Lateral inhibition +- Gating mechanisms +- Resource tracking + +### Step 5: Implement in PyTorch + +Use the hybrid approach: +1. Build explicit graph (NetworkX) +2. Add neural embeddings (PyTorch) +3. Implement GNN for inheritance (PyG) +4. Create clause evaluation networks + +## Summary: Why BrainSim III Matters + +### For Common Sense AI + +BrainSim III shows that **structure can encode reasoning** without symbolic programming: +- Facts emerge from graph patterns +- Learning happens through structure modification +- Confidence is gradual, not binary +- Exceptions are natural, not special cases + +### For Neural-Symbolic Integration + +It demonstrates a path between pure symbolic AI and pure neural networks: +- Explicit structure provides interpretability +- Weights provide uncertainty handling +- Agents enable autonomous learning +- Graph enables both symbolic and subsymbolic reasoning + +### For PyTorch/PyG Researchers + +The concepts translate to: +- **Graph structure**: Preserve with NetworkX + PyG Data +- **Inheritance**: Message passing along IS-A edges +- **Weights**: Learn with neural networks +- **Clauses**: Hypergraphs or attention mechanisms +- **Temporal**: Dynamic graphs with edge lifetimes +- **Reasoning**: Hybrid symbolic + neural queries + +## Conclusion + +BrainSim III represents a unique approach to AI that combines: +- **Graph-based knowledge representation** (explicit structure) +- **Weight-based confidence** (uncertainty handling) +- **Autonomous agents** (self-organizing learning) +- **Neural-inspired mechanisms** (sparse coding, gating, inhibition) +- **Logical reasoning** (transitive relationships, conditional clauses) + +For translation to PyTorch/PyTorch Geometric, the key is maintaining the **explicit graph structure** while leveraging neural networks for **learning and generalization**. This hybrid approach preserves the interpretability and reasoning capabilities of BrainSim III while gaining the learning power of deep learning. + +## Next Steps + +1. **Read detailed documentation**: + - [01_knowledge_representation.md](01_knowledge_representation.md) + - [02_inheritance_and_recursion.md](02_inheritance_and_recursion.md) + - [03_conditional_compound_logic.md](03_conditional_compound_logic.md) + - [04_neural_concepts_resource_management.md](04_neural_concepts_resource_management.md) + +2. **Explore the codebase**: + - [UKS/Thing.cs](../UKS/Thing.cs) - Node implementation + - [UKS/Relationship.cs](../UKS/Relationship.cs) - Edge implementation + - [UKS/UKS.cs](../UKS/UKS.cs) - Main knowledge store + - [Modules/Agents/](../BrainSimulator/Modules/Agents/) - Intelligent agents + +3. **Start implementing**: + - Build hybrid graph (NetworkX + PyTorch) + - Implement Thing/Relationship classes + - Add neural embeddings + - Create GNN for inheritance + - Implement clause evaluation + +## Additional Resources + +- **Official Documentation**: [DocsSource/Content/](../DocsSource/Content/) +- **README**: [../README.md](../README.md) +- **FAQ**: [../FAQ.md](../FAQ.md) From c28858cfb627e7ce488b2d91a03c72aff754933a Mon Sep 17 00:00:00 2001 From: naresrac Date: Sat, 15 Nov 2025 09:56:58 +0530 Subject: [PATCH 2/4] Add knowledge representation documentation for BrainSim III This document details the knowledge representation architecture in BrainSim III, focusing on the Universal Knowledge Store (UKS) and its graph-based model. It covers core concepts such as Things, Relationships, and Clauses, along with their implementations and principles of knowledge organization. --- user_docs/01_knowledge_representation.md | 577 +++++++++++++++++++++++ 1 file changed, 577 insertions(+) create mode 100644 user_docs/01_knowledge_representation.md diff --git a/user_docs/01_knowledge_representation.md b/user_docs/01_knowledge_representation.md new file mode 100644 index 0000000..40768a2 --- /dev/null +++ b/user_docs/01_knowledge_representation.md @@ -0,0 +1,577 @@ +# Knowledge Representation in BrainSim III + +## Overview + +BrainSim III implements knowledge representation through the Universal Knowledge Store (UKS), a custom in-memory graph database that models knowledge as a network of interconnected concepts. This document explores how the system represents and organizes information without relying on traditional symbolic programming. + +## Core Architecture + +### The Graph Model + +At its foundation, the UKS uses a property graph model with three fundamental elements: + +1. **Thing** (Node) - Represents any concept, object, attribute, action, or entity +2. **Relationship** (Edge) - Connects two Things with semantic meaning +3. **Clause** - Meta-relationship connecting two Relationships (conditional logic) + +``` +[Thing A] --[Relationship Type]--> [Thing B] +``` + +## Thing: Universal Node Abstraction + +### Concept + +A `Thing` is the most fundamental abstraction in BrainSim III. It can represent: +- Physical objects ("dog", "Fido", "table") +- Abstract concepts ("color", "happiness", "justice") +- Actions ("run", "eat", "think") +- Attributes ("red", "big", "fast") +- Relationship types themselves ("has", "is-a", "likes") +- Numbers, properties, categories + +**Key Insight**: The system is **self-referential** - relationship types are themselves Things in the graph. This eliminates the need for a separate schema layer. + +### Implementation + +**File**: [UKS/Thing.cs](../UKS/Thing.cs) + +```csharp +public partial class Thing +{ + // Core identity + private string label = ""; // Human-readable identifier + object value; // Arbitrary attached data (V property) + + // Relationship lists (bidirectional navigation) + private List relationships; // Outgoing edges + private List relationshipsFrom; // Incoming edges + private List relationshipsAsType; // Where this is the rel type + + // Usage tracking (for learning/weighting) + public int useCount = 0; + public DateTime lastFiredTime; + + // Implicit string conversion for easy API usage + public static implicit operator Thing(string label) +} +``` + +### Key Properties + +**Label Management**: +- Case-insensitive (internally lowercase) +- Unique across the UKS +- Maintained in hash table ([ThingLabels.cs](../UKS/ThingLabels.cs)) for O(1) lookup +- Can contain dots (.) for attribute notation: "dog.brown.4legs" + +**Hierarchy Navigation**: +```csharp +public IList Parents // Direct ancestors via "is-a" +public IList Children // Direct descendants via "is-a" +public IEnumerable Ancestors // Recursive upward traversal +public IEnumerable Descendents // Recursive downward traversal +``` + +**Usage Tracking**: +- `useCount`: Increments when Thing is accessed +- `lastFiredTime`: Timestamp of last activation +- Used for determining relevance and pruning + +## Relationship: Semantic Edge + +### Concept + +A `Relationship` is a **weighted, directed edge** connecting two Things with semantic meaning defined by a relationship type (which is itself a Thing). + +**Structure**: `[source Thing] --[relType Thing]--> [target Thing]` + +Example: +``` +[Fido] --[is-a]--> [Dog] +[Dog] --[has]--> [Leg] +[Sky] --[has.color]--> [Blue] +``` + +### Implementation + +**File**: [UKS/Relationship.cs](../UKS/Relationship.cs) + +```csharp +public class Relationship +{ + // Core triple + public Thing source; // Subject + public Thing reltype; // Predicate (relationship type) + public Thing target; // Object + + // Conditional logic + private List clauses; // IF/BECAUSE conditions + public List clausesFrom; // Reverse links + + // Confidence/weight management + private float weight = 1; // Explicit confidence + private int hits = 0; // Usage success count + private int misses = 0; // Usage failure count + + // Temporal properties + public DateTime lastUsed; + public DateTime created; + private TimeSpan timeToLive; // For transient relationships + + // Meta properties + public bool GPTVerified; // LLM verification flag + public bool isStatement; // True statement vs. query pattern +} +``` + +### Key Features + +**1. Weight-Based Confidence** + +The system uses a hybrid weighting approach: +- **Explicit weight** (0-1 range): Set by programmer or agent +- **Implicit weight** (hits/misses ratio): Learned from usage + +```csharp +public float Value +{ + get + { + float retVal = Weight; + if (Hits != 0 && Misses != 0) + { + retVal = Hits / (Misses == 0 ? 0.1f : Misses); + } + return retVal; + } +} +``` + +**2. Bidirectional Navigation** + +Every relationship automatically maintains three linkages: +- Added to `source.relationships` (outgoing) +- Added to `target.relationshipsFrom` (incoming) +- Added to `reltype.relationshipsAsType` (all uses of this type) + +This enables efficient queries in any direction. + +**3. Transient Relationships** + +Relationships can have a Time-To-Live (TTL): +```csharp +relationship.TimeToLive = TimeSpan.FromSeconds(30); +``` + +A background timer ([UKS.cs:46](../UKS/UKS.cs#L46)) removes expired relationships, enabling: +- Working memory (temporary associations) +- Attention mechanisms +- Short-term context + +## Clause: Conditional Meta-Relationships + +### Concept + +A `Clause` is a **relationship between relationships**, enabling conditional logic without symbolic programming. + +**Structure**: `[Relationship A] --[clause type]--> [Relationship B]` + +Clause types include: +- `IF`: Conditional dependency +- `BECAUSE`: Causal relationship +- `UNLESS`: Exception handling +- Custom clause types (extensible) + +### Implementation + +```csharp +public class Clause +{ + public Thing clauseType; // "IF", "BECAUSE", etc. + public Relationship clause; // Target relationship +} +``` + +**Example**: +``` +Statement: "Birds can fly" +[Bird] --[can]--> [Fly] + +Conditional: "Birds can fly IF they are not penguins" +[Bird] --[can]--> [Fly] IF [Bird] --[is-not]--> [Penguin] +``` + +### Usage in Code + +From [UKS.cs:586](../UKS/UKS.cs#L586): +```csharp +public Relationship AddClause(Relationship r1, Thing clauseType, + Thing source, Thing relType, Thing target) +{ + // Create conditional relationship (not a statement) + Relationship rTemp = new() { + source = source, + reltype = relType, + target = target, + Weight = .9f, + isStatement = false // This is a condition, not a fact + }; + + // Handle IF clauses by creating instances + if (clauseType.Label.ToLower() == "if" && r1.isStatement) + { + // Create a new instance of the source + Thing newInstance = GetOrAddThing(r1.source.Label + "*", r1.source); + // Move relationship to instance level + rRoot = newInstance.AddRelationship(r1.target, r1.relType, false); + AddStatement(rRoot.source.Label, "hasProperty", "isInstance"); + } + + // Attach the clause + rRoot.AddClause(clauseType, rTemp); + return rRoot; +} +``` + +## Knowledge Organization Principles + +### 1. Information is Singular + +**Concept**: Each piece of information exists in exactly one canonical location. + +**Implementation**: +- Labels are unique identifiers +- Hash table lookup ensures single Thing per concept +- Relationships deduplicated on creation ([Thing.cs:322](../UKS/Thing.cs#L322)) + +**Example**: +```csharp +Thing dog1 = uks.GetOrAddThing("dog"); // Creates if doesn't exist +Thing dog2 = uks.GetOrAddThing("dog"); // Returns same instance +// dog1 == dog2 (same object reference) +``` + +### 2. Structure + Interconnection = Facts + +**Concept**: Knowledge emerges from the structure of the graph and how things interconnect, not from data stored in nodes. + +**Example**: +``` +[Fido] + --[is-a]--> [Dog] + --[has]--> [Color.Brown] + --[has]--> [Tail] + +[Dog] + --[is-a]--> [Animal] + --[has]--> [Leg] (count: 4) + --[can]--> [Bark] +``` + +Facts derivable: +- Fido is an animal (transitive is-a) +- Fido can bark (inherited capability) +- Fido has 4 legs (inherited structure) +- Fido is brown (direct attribute) + +### 3. Directionality + +**Concept**: Relationships are directed, but the system maintains inverse relationships automatically. + +**Implementation**: +Certain relationship types have `inverseOf` property. When creating a relationship with an inverse type, the system automatically creates the reverse relationship. + +**File**: [UKS.Statement.cs](../UKS/UKS.Statement.cs) (part of UKS partial class) + +**Example**: +``` +"parent-of" inverseOf "child-of" + +Adding: [John] --[parent-of]--> [Mary] +Automatically creates: [Mary] --[child-of]--> [John] +``` + +### 4. Self-Referential Type System + +**Concept**: Relationship types are themselves Things in the UKS, eliminating the need for a rigid schema. + +**Bootstrap** ([UKS.cs:CreateInitialStructure](../UKS/UKS.cs)): +``` +Thing (root) +├── RelationshipType +│ ├── is-a +│ ├── has +│ ├── has-child +│ └── ... (custom types) +├── Object +├── Action +└── Properties + ├── isTransitive + ├── isCommutative + ├── isExclusive + └── allowMultiple +``` + +This enables: +- Runtime definition of new relationship types +- Properties on relationship types (transitive, commutative, etc.) +- Query relationships by their properties + +## Knowledge Representation Without Symbolic Programming + +### Traditional Approach (Symbolic AI) + +```python +# Explicit rules and structures +class Animal: + def __init__(self, name, legs): + self.name = name + self.legs = legs + +class Dog(Animal): + def bark(self): + return "woof" + +# Hard-coded logic +if isinstance(animal, Dog): + animal.bark() +``` + +### BrainSim III Approach (Structural AI) + +``` +# Structure defines behavior +[Dog] + --[is-a]--> [Animal] + --[has]--> [Leg] (count: 4) + --[can]--> [Bark] + +# Query determines behavior +Query: What can a dog do? +Result: Follow "can" relationships → Bark +``` + +**Advantages**: +1. **Flexibility**: Add new concepts without modifying code +2. **Learning**: Relationships can be created from experience +3. **Gradual confidence**: Weight-based certainty vs. binary true/false +4. **Exception handling**: Conditional clauses override inherited attributes +5. **Natural reasoning**: Query traversal mimics associative thinking + +## Reasoning Through Structure + +### Inheritance Chains + +The system follows `is-a` relationships to inherit properties: + +``` +Query: "What color is Fido?" + +Graph: +[Fido] --[is-a]--> [Dog] +[Dog] --[has.color]--> [Brown] + +Process: +1. Check Fido's direct relationships for "has.color" → Not found +2. Follow "is-a" to Dog +3. Check Dog's relationships for "has.color" → Found: Brown +4. Return: Brown (with inherited confidence weight) +``` + +**Implementation**: [Thing.cs:276](../UKS/Thing.cs#L276) - `FollowTransitiveRelationships()` + +### Conflict Resolution + +When multiple inherited or direct attributes conflict, the system uses: + +1. **Exclusivity detection**: Common parents with `isExclusive` property +2. **Weight comparison**: Higher-weighted relationship wins +3. **Specificity**: Direct attributes override inherited ones +4. **Negation handling**: "not X" conflicts with "X" + +**Implementation**: [UKS.cs:196](../UKS/UKS.cs#L196) - `RelationshipsAreExclusive()` + +**Example**: +``` +[Animal] --[has.color]--> [Brown] +[Bird] --[is-a]--> [Animal] +[Bluebird] --[is-a]--> [Bird] +[Bluebird] --[has.color]--> [Blue] (Weight: 1.0, direct) + +Query: "What color is Bluebird?" +Result: Blue (direct wins over inherited Brown) +``` + +### Compound Logic + +Complex logical expressions are built through clause chains: + +``` +"Birds fly IF they have wings UNLESS they are penguins" + +[Bird] --[can]--> [Fly] + ├─ IF: [Bird] --[has]--> [Wings] + └─ UNLESS: [Bird] --[is-a]--> [Penguin] +``` + +## Distributed Representation + +### Concept + +Knowledge is distributed across the graph rather than localized in individual nodes. This provides: +- **Redundancy**: Multiple paths to same conclusion +- **Resilience**: Loss of nodes doesn't eliminate knowledge +- **Associative recall**: Query spreads activation across related concepts + +### Example + +Knowledge about "Fido": +``` +Direct node: +[Fido] V: + +Distributed properties: +[Fido] --[is-a]--> [Dog] +[Fido] --[has.owner]--> [John] +[Fido] --[has.color]--> [Brown] +[Fido] --[likes]--> [Tennis-Ball] + +Inherited properties (via Dog): +[Dog] --[has]--> [Leg] (4) +[Dog] --[can]--> [Bark] +[Dog] --[is-a]--> [Animal] + +Contextual associations: +[John] --[has.pet]--> [Fido] +[Park] --[contains]--> [Fido] (transient, TTL: 1 hour) +``` + +Querying "Fido" activates: +- Direct Thing node +- All relationships (outgoing/incoming) +- Inherited attributes from Dog/Animal +- Associated contexts (owner, location) + +## Comparison to Neural Networks + +| Aspect | Neural Networks (PyTorch) | BrainSim III UKS | +|--------|---------------------------|-------------------| +| **Representation** | Distributed activations in weight matrices | Explicit graph structure | +| **Learning** | Gradient descent on continuous functions | Weight adjustment + structure modification | +| **Interpretability** | Black box (hard to explain) | White box (traceable reasoning) | +| **Symbolic reasoning** | Poor (requires neurosymbolic hybrid) | Native (graph traversal) | +| **Generalization** | Pattern matching, interpolation | Inheritance, transitive properties | +| **Memory** | Compressed in weights | Explicit storage of facts | +| **Reasoning type** | Associative, implicit | Logical, explicit | + +## Implementing in PyTorch/PyTorch Geometric + +### Strategy 1: Graph Neural Network Representation + +Use PyTorch Geometric to learn embeddings while preserving structure: + +```python +import torch +from torch_geometric.nn import GCNConv +from torch_geometric.data import Data + +# Node features: Thing embeddings +x = torch.tensor([[...], [...], ...]) # One vector per Thing + +# Edge index: Relationships +edge_index = torch.tensor([[source_ids...], [target_ids...]]) + +# Edge features: Relationship types + weights +edge_attr = torch.tensor([[rel_type_embedding, weight], ...]) + +# Graph data object +data = Data(x=x, edge_index=edge_index, edge_attr=edge_attr) + +# GNN layer +class UKS_GNN(torch.nn.Module): + def __init__(self): + super().__init__() + self.conv1 = GCNConv(in_channels, hidden_channels) + self.conv2 = GCNConv(hidden_channels, out_channels) + + def forward(self, x, edge_index, edge_attr): + x = self.conv1(x, edge_index, edge_attr) + x = F.relu(x) + x = self.conv2(x, edge_index, edge_attr) + return x +``` + +### Strategy 2: Hybrid Symbolic-Neural + +Maintain explicit graph structure in Python + use neural networks for: +- Thing embeddings (learned representations) +- Relationship weight prediction +- Query relevance scoring + +```python +import networkx as nx +import torch + +class HybridUKS: + def __init__(self): + self.graph = nx.DiGraph() # Explicit structure + self.embeddings = {} # Learned representations + self.encoder = ThingEncoder() # Neural encoder + + def add_thing(self, label): + self.graph.add_node(label) + self.embeddings[label] = self.encoder.encode(label) + + def add_relationship(self, source, reltype, target, weight=1.0): + self.graph.add_edge(source, target, + reltype=reltype, weight=weight) + + def query(self, source, reltype): + # Use neural network to rank candidate targets + candidates = self.graph.successors(source) + scores = self.score_model( + self.embeddings[source], + self.embeddings[reltype], + [self.embeddings[c] for c in candidates] + ) + return sorted(zip(candidates, scores), + key=lambda x: -x[1]) +``` + +### Strategy 3: Knowledge Graph Embeddings + +Use embedding techniques (TransE, RotatE, DistMult): + +```python +class TransE(torch.nn.Module): + def __init__(self, num_entities, num_relations, dim): + super().__init__() + self.entity_embeddings = nn.Embedding(num_entities, dim) + self.relation_embeddings = nn.Embedding(num_relations, dim) + + def forward(self, head, relation, tail): + # TransE: h + r ≈ t + h = self.entity_embeddings(head) + r = self.relation_embeddings(relation) + t = self.entity_embeddings(tail) + return -torch.norm(h + r - t, p=2, dim=1) +``` + +## Key Takeaways for PyTorch Implementation + +1. **Preserve explicit structure**: Don't compress everything into embeddings +2. **Hybrid approach**: Use neural networks for learning, graphs for reasoning +3. **Maintain interpretability**: Keep traceable paths for explaining decisions +4. **Implement weight dynamics**: hits/misses tracking for relationship confidence +5. **Support transient connections**: TTL mechanisms for working memory +6. **Enable meta-relationships**: Clauses as higher-order graph structures +7. **Build incrementally**: Start with Thing/Relationship, add inheritance, then clauses + +## References + +- [Thing.cs](../UKS/Thing.cs) - Node implementation +- [Relationship.cs](../UKS/Relationship.cs) - Edge implementation +- [UKS.cs](../UKS/UKS.cs) - Main knowledge store +- [UKS.Query.cs](../UKS/UKS.Query.cs) - Query engine +- [UKS.Statement.cs](../UKS/UKS.Statement.cs) - Statement API From 08ed25282cf5d7d80545cda73096d9d2767d95c9 Mon Sep 17 00:00:00 2001 From: naresrac Date: Sat, 15 Nov 2025 09:58:00 +0530 Subject: [PATCH 3/4] Add documentation for inheritance and recursion in BrainSim III This document provides an in-depth overview of inheritance and recursion in BrainSim III, detailing concepts like the IS-A relationship, direct parent/child relationships, recursive traversal, attribute inheritance, multiple inheritance, attribute bubbling, redundancy removal, dynamic class creation, and exception handling. It includes code snippets and examples to illustrate the implementation of these concepts. --- user_docs/02_inheritance_and_recursion.md | 755 ++++++++++++++++++++++ 1 file changed, 755 insertions(+) create mode 100644 user_docs/02_inheritance_and_recursion.md diff --git a/user_docs/02_inheritance_and_recursion.md b/user_docs/02_inheritance_and_recursion.md new file mode 100644 index 0000000..f376327 --- /dev/null +++ b/user_docs/02_inheritance_and_recursion.md @@ -0,0 +1,755 @@ +# Inheritance and Recursion in BrainSim III + +## Overview + +BrainSim III implements a sophisticated inheritance system that mirrors object-oriented programming concepts but operates entirely through graph structure. The system supports multiple inheritance, attribute bubbling, exception handling, and dynamic class creation—all without traditional class definitions. + +## The IS-A Relationship: Foundation of Inheritance + +### Concept + +The `is-a` relationship is the primary mechanism for building taxonomies and enabling inheritance. It creates a directed acyclic graph (DAG) representing class hierarchies. + +**File**: [Thing.cs:36](../UKS/Thing.cs#L36) + +```csharp +public static Thing IsA { get => ThingLabels.GetThing("is-a"); } +``` + +### Hierarchy Example + +``` +Thing (root) +├── Object +│ ├── Animal +│ │ ├── Mammal +│ │ │ ├── Dog +│ │ │ │ ├── Fido (instance) +│ │ │ │ └── Rover (instance) +│ │ │ └── Cat +│ │ └── Bird +│ │ ├── Sparrow +│ │ └── Penguin +│ └── PhysicalObject +└── Action + ├── Move + │ ├── Walk + │ └── Fly + └── Communicate + ├── Bark + └── Speak +``` + +## Direct Parent/Child Relationships + +### Implementation + +[Thing.cs:154-159](../UKS/Thing.cs#L154-L159): + +```csharp +// Direct ancestors +public IList Parents { get => RelationshipsOfType(IsA, false); } + +// Direct descendants +public IList Children { get => RelationshipsOfType(IsA, true); } + +private IList RelationshipsOfType(Thing relType, bool useRelationshipFrom) +{ + IList retVal = new List(); + if (!useRelationshipFrom) + { + // Get targets of outgoing "is-a" relationships + foreach (Relationship r in relationships) + if (r.relType == relType && r.source == this) + retVal.Add(r.target); + } + else + { + // Get sources of incoming "is-a" relationships + foreach (Relationship r in relationshipsFrom) + if (r.relType == relType && r.target == this) + retVal.Add(r.source); + } + return retVal; +} +``` + +### Usage + +```csharp +Thing dog = uks.Labeled("Dog"); +IList parents = dog.Parents; // Returns: [Mammal] +IList children = dog.Children; // Returns: [Fido, Rover, ...] +``` + +## Recursive Ancestor/Descendent Traversal + +### Transitive Relationship Following + +**File**: [Thing.cs:276-302](../UKS/Thing.cs#L276-L302) + +```csharp +private IList FollowTransitiveRelationships( + Thing relType, + bool followUpwards = true, + Thing searchTarget = null) +{ + List retVal = new(); + retVal.Add(this); + if (this == searchTarget) return retVal; + + // Breadth-first traversal + for (int i = 0; i < retVal.Count; i++) + { + Thing t = retVal[i]; + IList relationshipsToFollow = + followUpwards ? t.Relationships : t.RelationshipsFrom; + + foreach (Relationship r in relationshipsToFollow) + { + Thing thingToAdd = followUpwards ? r.target : r.source; + if (r.reltype == relType) + { + if (!retVal.Contains(thingToAdd)) + retVal.Add(thingToAdd); + } + if (searchTarget == thingToAdd) + return retVal; + } + } + if (searchTarget != null) retVal.Clear(); + return retVal; +} +``` + +### Ancestor Access + +[Thing.cs:199-218](../UKS/Thing.cs#L199-L218): + +```csharp +public IList AncestorList() +{ + return FollowTransitiveRelationships(IsA, true); +} + +public IEnumerable Ancestors +{ + get + { + IList ancestors = AncestorList(); + for (int i = 0; i < ancestors.Count; i++) + { + Thing child = ancestors[i]; + yield return child; + } + } +} + +public bool HasAncestor(Thing t) +{ + var x = FollowTransitiveRelationships(IsA, true, t); + return x.Count != 0; +} +``` + +### Example Usage + +```csharp +Thing fido = uks.Labeled("Fido"); + +// Get all ancestors +IList ancestors = fido.AncestorList(); +// Returns: [Fido, Dog, Mammal, Animal, Object, Thing] + +// Check specific ancestor +bool isDog = fido.HasAncestor("Dog"); // true +bool isBird = fido.HasAncestor("Bird"); // false + +// Iterate through ancestors +foreach (Thing ancestor in fido.Ancestors) +{ + Console.WriteLine(ancestor.Label); +} +``` + +## Attribute Inheritance + +### Concept + +Things inherit attributes (relationships) from their ancestors. When querying for a property not directly attached to a Thing, the system traverses upward through the `is-a` hierarchy. + +### Query with Inheritance + +**File**: [UKS.cs:158-167](../UKS/UKS.cs#L158-L167) + +```csharp +List RelationshipTree(Thing t, Thing relType) +{ + List results = new(); + + // Direct relationships + results.AddRange(t.Relationships.FindAll(x => x.reltype == relType)); + + // Inherited from ancestors + foreach (Thing t1 in t.Ancestors) + results.AddRange(t1.Relationships.FindAll(x => x.reltype == relType)); + + // Relationships from descendants (for reverse queries) + foreach (Thing t1 in t.Descendents) + results.AddRange(t1.Relationships.FindAll(x => x.reltype == relType)); + + return results; +} +``` + +### Example: Inherited Properties + +``` +Structure: +[Animal] --[has]--> [Leg] +[Dog] --[is-a]--> [Animal] +[Dog] --[can]--> [Bark] +[Fido] --[is-a]--> [Dog] +[Fido] --[has.color]--> [Brown] + +Query: "What does Fido have?" +Results: +1. [Fido] --[has.color]--> [Brown] (direct) +2. [Fido] --[can]--> [Bark] (inherited from Dog) +3. [Fido] --[has]--> [Leg] (inherited from Animal) +``` + +## Multiple Inheritance + +### Concept + +BrainSim III fully supports multiple inheritance—a Thing can have multiple parents, inheriting attributes from all of them. + +### Implementation + +[Thing.cs:506-514](../UKS/Thing.cs#L506-L514): + +```csharp +public void AddParent(Thing newParent) +{ + if (newParent == null) return; + if (!Parents.Contains(newParent)) + { + AddRelationship(newParent, IsA); + } +} +``` + +### Example: Diamond Problem Handling + +``` + [Vehicle] + / \ + / \ + [LandVehicle] [WaterVehicle] + \ / + \ / + [AmphibiousCar] +``` + +**Graph Structure**: +```csharp +Thing vehicle = uks.GetOrAddThing("Vehicle", "Object"); +Thing landVehicle = uks.GetOrAddThing("LandVehicle", vehicle); +Thing waterVehicle = uks.GetOrAddThing("WaterVehicle", vehicle); +Thing amphibiousCar = uks.GetOrAddThing("AmphibiousCar", landVehicle); +amphibiousCar.AddParent(waterVehicle); // Multiple inheritance + +// AmphibiousCar.Parents → [LandVehicle, WaterVehicle] +// AmphibiousCar.AncestorList() → [AmphibiousCar, LandVehicle, WaterVehicle, Vehicle, Object, Thing] +``` + +**Conflict Resolution**: When both parents have the same relationship type, the system uses: +1. **Weight comparison**: Higher weight wins +2. **Exclusivity detection**: Check if targets are mutually exclusive +3. **Specificity**: Direct attributes override inherited + +## Attribute Bubbling: Bottom-Up Generalization + +### Concept + +**Attribute bubbling** is the process of moving common attributes from children up to their parent, creating generalizations. This is a key learning mechanism in BrainSim III. + +**Module**: [ModuleAttributeBubble.cs](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs) + +### Algorithm + +**File**: [ModuleAttributeBubble.cs:82-201](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs#L82-L201) + +```csharp +void BubbleChildAttributes(Thing t) +{ + if (t.Children.Count == 0) return; + if (t.Label == "unknownObject") return; + + // 1. Build a list of all relationships that children have + List itemCounts = new(); + foreach (Thing t1 in t.ChildrenWithSubclasses) + { + foreach (Relationship r in t1.Relationships) + { + if (r.reltype == Thing.IsA) continue; + Thing useRelType = GetInstanceType(r.reltype); + + RelDest foundItem = itemCounts.FindFirst( + x => x.relType == useRelType && x.target == r.target); + if (foundItem == null) + { + foundItem = new RelDest { relType = useRelType, target = r.target }; + itemCounts.Add(foundItem); + } + foundItem.relationships.Add(r); + } + } + + // 2. Sort by frequency + var sortedItems = itemCounts.OrderByDescending(x => x.relationships.Count); + + // 3. Bubble relationships that appear in > 50% of children + foreach (RelDest rr in sortedItems) + { + float totalCount = t.Children.Count; + float positiveCount = rr.relationships.FindAll(x => x.Weight > .5f).Count; + + // Count conflicting relationships + float negativeCount = 0; + foreach (var other in sortedItems) + { + if (RelationshipsConflict(rr, other)) + negativeCount += other.relationships.Count; + } + + // Calculate confidence weight + float deltaWeight = positiveCount - negativeCount; + float targetWeight = CalculateWeight(deltaWeight); + + if (positiveCount > totalCount / 2) + { + // Bubble the property to parent + Relationship r = t.AddRelationship(rr.target, rr.relType); + r.Weight = targetWeight; + + // Remove from children (now redundant) + foreach (Thing child in t.Children) + { + child.RemoveRelationship(rr.target, rr.relType); + } + } + } +} +``` + +### Example: Learning Dog Properties + +**Initial State**: +``` +[Dog] +├── [Fido] --[has.color]--> [Brown], --[has]--> [Tail], --[has.legs]--> [4] +├── [Rover] --[has.color]--> [Brown], --[has]--> [Tail], --[has.legs]--> [4] +├── [Spot] --[has.color]--> [White], --[has]--> [Tail], --[has.legs]--> [4] +└── [Rex] --[has.color]--> [Black], --[has]--> [Tail], --[has.legs]--> [4] +``` + +**After Attribute Bubbling**: +``` +[Dog] --[has]--> [Tail] (Weight: 0.95) ← Bubbled (100% have it) + --[has.legs]--> [4] (Weight: 0.95) ← Bubbled (100% have it) + +├── [Fido] --[has.color]--> [Brown] (NOT bubbled - only 25% Brown) +├── [Rover] --[has.color]--> [Brown] +├── [Spot] --[has.color]--> [White] +└── [Rex] --[has.color]--> [Black] +``` + +**Reasoning**: All dogs have tails and 4 legs (generalized), but color varies (kept specific). + +## Redundancy Removal: Cleaning Inherited Duplicates + +### Concept + +After bubbling, some children may have relationships that are now redundant with parent attributes. The **RemoveRedundancy** module cleans these up. + +**Module**: [ModuleRemoveRedundancy.cs](../BrainSimulator/Modules/Agents/ModuleRemoveRedundancy.cs) + +### Algorithm + +[ModuleRemoveRedundancy.cs:59-81](../BrainSimulator/Modules/Agents/ModuleRemoveRedundancy.cs#L59-L81): + +```csharp +private void RemoveRedundantAttributes(Thing t) +{ + foreach (Thing parent in t.Parents) + { + // Get all relationships including inherited ones + List relationshipsWithInheritance = + theUKS.GetAllRelationships(new List { parent }); + + // Check each relationship of this Thing + for (int i = 0; i < t.Relationships.Count; i++) + { + Relationship r = t.Relationships[i]; + + // Find matching relationship in inheritance chain + Relationship rMatch = relationshipsWithInheritance.FindFirst( + x => x.source != r.source && // Different source + x.reltype == r.reltype && // Same type + x.target == r.target); // Same target + + // If parent has strong version, reduce child's weight + if (rMatch != null && rMatch.Weight > 0.8f) + { + r.Weight -= 0.1f; + if (r.Weight < 0.5f) + { + t.RemoveRelationship(r); // Remove redundant + i--; + } + } + } + } +} +``` + +### Example + +**Before Redundancy Removal**: +``` +[Dog] --[has]--> [Tail] (Weight: 0.95) +[Fido] --[is-a]--> [Dog] + --[has]--> [Tail] (Weight: 0.80, redundant!) +``` + +**After**: +``` +[Dog] --[has]--> [Tail] (Weight: 0.95) +[Fido] --[is-a]--> [Dog] + (Tail relationship removed - inherited from Dog) +``` + +## Dynamic Class Creation + +### Concept + +When multiple children share specific attribute combinations, the system can automatically create **intermediate classes** to capture these patterns. + +**Module**: [ModuleClassCreate.cs](../BrainSimulator/Modules/Agents/ModuleClassCreate.cs) + +### Algorithm + +[ModuleClassCreate.cs:68-106](../BrainSimulator/Modules/Agents/ModuleClassCreate.cs#L68-L106): + +```csharp +void HandleClassWithCommonAttributes(Thing t) +{ + // 1. Build list of attribute combinations + List attributes = new(); + foreach (Thing child in t.ChildrenWithSubclasses) + { + foreach (Relationship r in child.Relationships) + { + if (r.reltype == Thing.IsA) continue; + + RelDest foundItem = attributes.FindFirst( + x => x.relType == r.reltype && x.target == r.target); + if (foundItem == null) + { + foundItem = new RelDest { relType = r.reltype, target = r.target }; + attributes.Add(foundItem); + } + foundItem.relationships.Add(r); + } + } + + // 2. Create intermediate parent for common attribute sets + foreach (var key in attributes) + { + if (key.relationships.Count >= minCommonAttributes) + { + // Create new subclass with attribute in name + Thing newParent = theUKS.GetOrAddThing( + t.Label + "." + key.relType + "." + key.target, t); + newParent.AddRelationship(key.target, key.relType); + + // Move matching children to new parent + foreach (Relationship r in key.relationships) + { + Thing child = r.source; + child.AddParent(newParent); + child.RemoveParent(t); + } + } + } +} +``` + +### Example: Auto-Creating Bird Subcategories + +**Initial**: +``` +[Bird] +├── [Robin] --[has.color]--> [Red] +├── [Cardinal] --[has.color]--> [Red] +├── [Bluebird] --[has.color]--> [Blue] +└── [Bluejay] --[has.color]--> [Blue] +``` + +**After Dynamic Class Creation** (if 2+ birds share color): +``` +[Bird] +├── [Bird.has.color.Red] ← Auto-created +│ --[has.color]--> [Red] +│ ├── [Robin] +│ └── [Cardinal] +└── [Bird.has.color.Blue] ← Auto-created + --[has.color]--> [Blue] + ├── [Bluebird] + └── [Bluejay] +``` + +## Exceptions: Overriding Inheritance + +### Concept + +Things can have **exception relationships** that override inherited attributes. This is handled through direct attributes with higher weights and exclusivity detection. + +### Conflict Detection + +[UKS.cs:196-295](../UKS/UKS.cs#L196-L295): + +```csharp +private bool RelationshipsAreExclusive(Relationship r1, Relationship r2) +{ + // Same source, different targets from exclusive category + if (r1.source == r2.source && r1.relType == r2.relType) + { + List commonParents = FindCommonParents(r1.target, r2.target); + foreach (Thing parent in commonParents) + { + if (parent.HasProperty("isExclusive")) + return true; // Color, count, etc. + } + } + + // Negation conflicts + bool r1HasNot = r1.relType.GetAttributes().Any(x => x.Label == "not"); + bool r2HasNot = r2.relType.GetAttributes().Any(x => x.Label == "not"); + if (r1HasNot != r2HasNot && r1.target == r2.target) + return true; // "can fly" vs "cannot fly" + + return false; +} +``` + +### Example: Penguins Don't Fly + +``` +[Bird] --[can]--> [Fly] (Weight: 0.95, inherited) + +[Penguin] --[is-a]--> [Bird] + --[cannot]--> [Fly] (Weight: 1.0, direct exception) + +Query: "Can a penguin fly?" +Process: +1. Check Penguin relationships: cannot Fly (Weight: 1.0) +2. Check inherited from Bird: can Fly (Weight: 0.95) +3. Detect conflict: "cannot" vs "can" +4. Higher weight + direct wins → Result: No +``` + +## Recursion Patterns + +### 1. Depth-First Ancestor Traversal + +```csharp +public void PrintAncestryTree(Thing t, int depth = 0) +{ + Console.WriteLine(new string(' ', depth * 2) + t.Label); + foreach (Thing parent in t.Parents) + { + PrintAncestryTree(parent, depth + 1); + } +} +``` + +### 2. Breadth-First Relationship Search + +[Thing.cs:276-302](../UKS/Thing.cs#L276-L302): Implemented in `FollowTransitiveRelationships()` + +```csharp +// Breadth-first ensures closest ancestors checked first +List queue = new() { startThing }; +for (int i = 0; i < queue.Count; i++) +{ + Thing current = queue[i]; + foreach (Relationship r in current.Relationships) + { + if (r.reltype == targetRelType && !queue.Contains(r.target)) + queue.Add(r.target); + } +} +``` + +### 3. Circular Reference Protection + +The system prevents infinite loops through visited-set tracking: + +```csharp +List visited = new(); + +void TraverseGraph(Thing t) +{ + if (visited.Contains(t)) return; // Already visited + visited.Add(t); + + foreach (Thing child in t.Children) + { + TraverseGraph(child); + } +} +``` + +## Implementing in PyTorch/PyTorch Geometric + +### Strategy 1: Hierarchical Graph Neural Network + +```python +import torch +import torch.nn as nn +from torch_geometric.nn import MessagePassing + +class HierarchicalGNN(MessagePassing): + def __init__(self, in_channels, out_channels): + super().__init__(aggr='add') + self.lin = nn.Linear(in_channels, out_channels) + + def forward(self, x, edge_index, edge_type): + # Separate "is-a" edges from other relationship types + is_a_mask = (edge_type == IS_A_TYPE_ID) + is_a_edges = edge_index[:, is_a_mask] + other_edges = edge_index[:, ~is_a_mask] + + # Propagate along is-a hierarchy (inheritance) + x_inherited = self.propagate(is_a_edges, x=x, edge_type=edge_type[is_a_mask]) + + # Propagate along other relationships + x_relational = self.propagate(other_edges, x=x, edge_type=edge_type[~is_a_mask]) + + # Combine inherited and direct features + return self.lin(x + x_inherited + x_relational) + + def message(self, x_j, edge_type): + # x_j are features of neighbor nodes + # Weight by relationship type and inheritance distance + return x_j +``` + +### Strategy 2: Explicit Inheritance in Graph Structure + +```python +import networkx as nx + +class InheritanceGraph: + def __init__(self): + self.graph = nx.DiGraph() + + def add_thing(self, label, parent=None): + self.graph.add_node(label) + if parent: + self.graph.add_edge(label, parent, reltype='is-a') + + def get_ancestors(self, label): + """Recursive ancestor collection""" + ancestors = [] + node = label + while True: + parents = [n for n in self.graph.successors(node) + if self.graph[node][n].get('reltype') == 'is-a'] + if not parents: + break + ancestors.extend(parents) + node = parents[0] # Single inheritance + return ancestors + + def get_inherited_attributes(self, label): + """Collect attributes from ancestors""" + attributes = {} + for ancestor in [label] + self.get_ancestors(label): + for neighbor in self.graph.successors(ancestor): + edge_data = self.graph[ancestor][neighbor] + reltype = edge_data.get('reltype') + if reltype != 'is-a': + attributes[reltype] = neighbor + return attributes + + def bubble_attributes(self, parent_label): + """Move common child attributes to parent""" + children = [n for n in self.graph.predecessors(parent_label) + if self.graph[n][parent_label].get('reltype') == 'is-a'] + + # Count attribute frequency + attr_counts = {} + for child in children: + for neighbor in self.graph.successors(child): + edge_data = self.graph[child][neighbor] + reltype = edge_data.get('reltype') + if reltype != 'is-a': + key = (reltype, neighbor) + attr_counts[key] = attr_counts.get(key, 0) + 1 + + # Bubble if > 50% have it + threshold = len(children) / 2 + for (reltype, target), count in attr_counts.items(): + if count > threshold: + self.graph.add_edge(parent_label, target, reltype=reltype) + # Remove from children + for child in children: + if self.graph.has_edge(child, target): + self.graph.remove_edge(child, target) +``` + +### Strategy 3: Neural Inheritance with Learned Weights + +```python +class NeuralInheritance(nn.Module): + def __init__(self, embedding_dim): + super().__init__() + self.inheritance_weight = nn.Linear(embedding_dim * 2, 1) + + def forward(self, child_emb, parent_emb, parent_attr_emb): + """ + Determine how much of parent's attribute to inherit + """ + # Concatenate child and parent embeddings + combined = torch.cat([child_emb, parent_emb], dim=-1) + + # Learned inheritance weight + weight = torch.sigmoid(self.inheritance_weight(combined)) + + # Apply inheritance + inherited_attr = weight * parent_attr_emb + return inherited_attr +``` + +## Key Takeaways + +1. **IS-A as directed edges**: Simple graph structure enables complex inheritance +2. **Transitive traversal**: Breadth-first search for inheritance chains +3. **Multiple inheritance**: DAG structure supports diamond patterns +4. **Attribute bubbling**: Bottom-up generalization through frequency analysis +5. **Redundancy removal**: Top-down cleanup after bubbling +6. **Dynamic classes**: Auto-create intermediate nodes for pattern grouping +7. **Exception handling**: Weight + exclusivity for override resolution +8. **Recursion protection**: Visited-set tracking prevents infinite loops + +## References + +- [Thing.cs](../UKS/Thing.cs) - Parent/child relationships, traversal +- [UKS.cs](../UKS/UKS.cs) - Relationship trees, conflict detection +- [ModuleAttributeBubble.cs](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs) - Bottom-up generalization +- [ModuleRemoveRedundancy.cs](../BrainSimulator/Modules/Agents/ModuleRemoveRedundancy.cs) - Inheritance cleanup +- [ModuleClassCreate.cs](../BrainSimulator/Modules/Agents/ModuleClassCreate.cs) - Dynamic class formation From bfff5a73d0dc583c0fa3454d6bafa821e28e71d0 Mon Sep 17 00:00:00 2001 From: naresrac Date: Sat, 15 Nov 2025 09:58:41 +0530 Subject: [PATCH 4/4] Upload docs --- user_docs/03_conditional_compound_logic.md | 805 ++++++++++++++++++ .../04_neural_concepts_resource_management.md | 799 +++++++++++++++++ 2 files changed, 1604 insertions(+) create mode 100644 user_docs/03_conditional_compound_logic.md create mode 100644 user_docs/04_neural_concepts_resource_management.md diff --git a/user_docs/03_conditional_compound_logic.md b/user_docs/03_conditional_compound_logic.md new file mode 100644 index 0000000..25316ee --- /dev/null +++ b/user_docs/03_conditional_compound_logic.md @@ -0,0 +1,805 @@ +# Conditional and Compound Logic in BrainSim III + +## Overview + +BrainSim III implements complex logical reasoning through **structural relationships** rather than symbolic programming. The system supports conjunctive logic, conditional statements, temporal sequences, causal relationships, and nested logic—all represented as graph patterns with clauses. + +## Clause System: Relationships Between Relationships + +### Core Concept + +A **Clause** is a meta-relationship that connects two Relationships, enabling conditional and compound logic: + +``` +[Relationship A] --[Clause Type]--> [Relationship B] +``` + +This creates a second-order graph where edges themselves have edges. + +### Implementation + +**File**: [Relationship.cs:50-65](../UKS/Relationship.cs#L50-L65) + +```csharp +public class Clause +{ + public Thing clauseType; // "IF", "BECAUSE", "UNLESS", etc. + public Relationship clause; // The target relationship +} + +public class Relationship +{ + // ... source, reltype, target ... + + private List clauses = new(); + public List Clauses { get => clauses; set => clauses = value; } + + // Relationships that have this as a clause target + public List clausesFrom = new(); +} +``` + +### Clause Types + +The system defines several built-in clause types during initialization: + +**File**: UKS initialization creates: +``` +ClauseType (Thing) +├── IF (conditional prerequisite) +├── BECAUSE (causal explanation) +├── UNLESS (exception handling) +├── WHILE (temporal co-occurrence) +├── THEN (sequential consequence) +└── ... (extensible) +``` + +## Conditional Logic (IF Clauses) + +### Concept + +IF clauses make statements conditional. A relationship is only valid when its IF clause is satisfied. + +``` +Statement: R1 +Condition: R2 +Result: R1 IF R2 +``` + +### Implementation + +**File**: [UKS.cs:586-627](../UKS/UKS.cs#L586-L627) + +```csharp +public Relationship AddClause( + Relationship r1, // Main statement + Thing clauseType, // "IF", "BECAUSE", etc. + Thing source, // Clause relationship components + Thing relType, + Thing target) +{ + // Create the conditional relationship (not a statement itself) + Relationship rTemp = new() { + source = source, + reltype = relType, + target = target, + Weight = .9f, + isStatement = false // This is a condition, not a fact + }; + + // Check if this clause already exists + foreach (Thing t in r1.source.Children) + { + foreach (Relationship r in t.Relationships) + { + Clause? c = r.Clauses.FindFirst( + x => x?.clauseType == clauseType && x?.clause == rTemp); + if (c != null) return r; // Already exists + } + } + + // Determine if a new instance is needed + bool newInstanceNeeded = false; + if (clauseType.Label.ToLower() == "if" && r1.isStatement) + newInstanceNeeded = true; + if (clauseType.Label.ToLower() == "because") + r1.isStatement = true; + + Relationship rRoot = r1; + + if (newInstanceNeeded) + { + // Create a new instance of the source + Thing newInstance = GetOrAddThing(r1.source.Label + "*", r1.source); + + // Move the existing relationship to the instance level + r1.source.RemoveRelationship(r1); + rRoot = newInstance.AddRelationship(r1.target, r1.relType, false); + AddStatement(rRoot.source.Label, "hasProperty", "isInstance"); + } + + // Make rTemp into a real relationship + rTemp = rTemp.source.AddRelationship(rTemp.target, rTemp.relType, r1.isStatement); + + // Add the clause + rRoot.AddClause(clauseType, rTemp); + rRoot.isStatement = r1.isStatement; + return rRoot; +} +``` + +### Example: Birds Fly IF They Have Wings + +**Statement API**: +```csharp +// Base statement +Relationship r1 = uks.AddStatement("Bird", "can", "Fly"); + +// Add condition +uks.AddClause(r1, "IF", "Bird", "has", "Wings"); +``` + +**Graph Structure**: +``` +[Bird] --[can]--> [Fly] + └── IF: [Bird] --[has]--> [Wings] +``` + +**Reasoning Process**: +``` +Query: "Can a Bird fly?" +1. Find relationship: [Bird] --[can]--> [Fly] +2. Check clauses: IF [Bird] --[has]--> [Wings] +3. Verify condition: Does Bird have Wings? +4. If YES → Result: Bird can fly + If NO → Result: Uncertain or No +``` + +## Instance Creation for Conditionals + +### Concept + +When adding an IF clause to a general statement, the system creates an **instance** to avoid modifying the universal relationship. + +### Example: Penguins Can't Fly + +``` +Initial: [Bird] --[can]--> [Fly] + +Adding: [Bird] --[can]--> [Fly] IF [Bird] --[is-not]--> [Penguin] + +Results in: +[Bird] + ├── [Bird0] (instance) + │ --[can]--> [Fly] (isStatement: false) + │ └── IF: [Bird0] --[is-not]--> [Penguin] + │ --[hasProperty]--> [isInstance] + └── (Original Bird unchanged) +``` + +This preserves the general concept while creating a conditional variant. + +## Causal Logic (BECAUSE Clauses) + +### Concept + +BECAUSE clauses explain why a relationship exists, representing causal connections. + +``` +Effect: R1 +Cause: R2 +Result: R1 BECAUSE R2 +``` + +### Example: Motion Causes Blur + +``` +[Photo] --[has.property]--> [Blurry] + └── BECAUSE: [Camera] --[had]--> [Motion] +``` + +**Code**: +```csharp +Relationship effect = uks.AddStatement("Photo", "has.property", "Blurry"); +uks.AddClause(effect, "BECAUSE", "Camera", "had", "Motion"); +``` + +**Reasoning**: +``` +Query: "Why is the photo blurry?" +1. Find: [Photo] --[has.property]--> [Blurry] +2. Follow BECAUSE clause: [Camera] --[had]--> [Motion] +3. Result: "Because the camera had motion" +``` + +## Temporal Logic + +### 1. Sequential Relationships (THEN) + +**Concept**: One event follows another in time. + +``` +[Event A] --[leads-to]--> [Event B] + └── THEN: [Event B] --[occurs-after]--> [Event A] +``` + +**Example: Action Sequence** +``` +[Press-Button] --[causes]--> [Door-Opens] + └── THEN: [Door-Opens] --[occurs-after]--> [Press-Button] +``` + +### 2. Co-occurrence (WHILE) + +**Concept**: Two events happen simultaneously. + +``` +[Walk] --[simultaneous]--> [Chew-Gum] + └── WHILE: [Person] --[does]--> [Chew-Gum] +``` + +### 3. Temporal TTL Implementation + +**File**: [Relationship.cs:180-193](../UKS/Relationship.cs#L180-L193) + +```csharp +private TimeSpan timeToLive = TimeSpan.MaxValue; + +public TimeSpan TimeToLive +{ + get { return timeToLive; } + set + { + timeToLive = value; + if (timeToLive != TimeSpan.MaxValue) + AddToTransientList(); // Register for cleanup + } +} + +private void AddToTransientList() +{ + if (!UKS.transientRelationships.Contains(this)) + UKS.transientRelationships.Add(this); +} +``` + +**Cleanup Timer** [UKS.cs:46-78](../UKS/UKS.cs#L46-L78): +```csharp +static public List transientRelationships = new List(); +static Timer stateTimer; + +public UKS(bool clear = false) +{ + // Start timer: check every 1 second + stateTimer = new Timer(RemoveExpiredRelationships, autoEvent, 0, 1000); +} + +private void RemoveExpiredRelationships(Object stateInfo) +{ + if (isRunning) return; + isRunning = true; + + for (int i = transientRelationships.Count - 1; i >= 0; i--) + { + Relationship r = transientRelationships[i]; + + // Check if expired + if (r.TimeToLive != TimeSpan.MaxValue && + r.LastUsed + r.TimeToLive < DateTime.Now) + { + r.source.RemoveRelationship(r); + + // Clean up orphaned Things + if (r.reltype.Label == "has-child" && r.target?.Parents.Count == 0) + { + r.target.AddParent(ThingLabels.GetThing("unknownObject")); + } + + transientRelationships.Remove(r); + } + } + + isRunning = false; +} +``` + +**Example: Working Memory** +```csharp +// Robot sees object +Relationship sees = uks.AddStatement("Robot", "sees", "Ball"); +sees.TimeToLive = TimeSpan.FromSeconds(30); // Forget after 30 seconds + +// After 30 seconds with no access: relationship auto-deleted +``` + +## Compound Logic Patterns + +### 1. Conjunctive Logic (AND) + +**Concept**: Multiple conditions must all be true. + +**Graph Pattern**: +``` +[Result] --[requires]--> [Condition1] + --[requires]--> [Condition2] + --[requires]--> [Condition3] +``` + +**Example: Recipe Requirements** +``` +[Cake] --[requires]--> [Flour] + --[requires]--> [Sugar] + --[requires]--> [Eggs] + --[requires]--> [Heat] +``` + +**Query Implementation**: +```csharp +public bool AllConditionsMet(Thing result, Thing requiresRelType) +{ + List requirements = + result.Relationships.FindAll(x => x.relType == requiresRelType); + + foreach (Relationship req in requirements) + { + if (!VerifyCondition(req.target)) + return false; // Missing a requirement + } + return true; // All requirements met +} +``` + +### 2. Disjunctive Logic (OR) + +**Concept**: Any one of multiple conditions can be true. + +**Graph Pattern**: +``` +[Goal] --[achieved-by]--> [Method1] + --[achieved-by]--> [Method2] + --[achieved-by]--> [Method3] +``` + +**Example: Multiple Paths** +``` +[Open-Door] + --[achieved-by]--> [Use-Key] + --[achieved-by]--> [Use-Code] + --[achieved-by]--> [Biometric-Scan] +``` + +**Query**: Any successful path returns true. + +### 3. Nested Conditionals + +**Concept**: Clauses on clauses create multi-level logic. + +**Structure**: +``` +R1 IF R2 +R2 IF R3 +R3 IF R4 +``` + +**Example: Permission Hierarchy** +``` +[User] --[can]--> [Delete-File] + └── IF: [User] --[has]--> [Admin-Role] + └── IF: [User] --[passed]--> [Security-Check] + └── IF: [User] --[has]--> [Valid-Token] +``` + +**Recursive Clause Verification**: +```csharp +public bool VerifyClauseChain(Relationship r, HashSet visited) +{ + if (visited.Contains(r)) return false; // Circular dependency + visited.Add(r); + + // No clauses → unconditional truth + if (r.Clauses.Count == 0) return true; + + foreach (Clause c in r.Clauses) + { + if (c.clauseType.Label == "IF") + { + // Recursively verify IF clause + if (!VerifyClauseChain(c.clause, visited)) + return false; + } + } + return true; +} +``` + +## Exception Handling (UNLESS) + +### Concept + +UNLESS clauses create exceptions that override general rules. + +``` +General Rule: R1 +Exception: R2 +Result: R1 UNLESS R2 +``` + +### Example: Typical vs. Exceptional Cases + +``` +[Bird] --[can]--> [Fly] (Weight: 0.9) + └── UNLESS: [Bird] --[is-a]--> [Penguin] + +[Bird] --[can]--> [Fly] (Weight: 0.9) + └── UNLESS: [Bird] --[is-a]--> [Ostrich] +``` + +**Query Logic**: +```csharp +public bool CheckWithExceptions(Thing subject, Thing capability) +{ + // Find general capability + Relationship r = subject.Relationships.FindFirst( + x => x.relType == "can" && x.target == capability); + + if (r == null) return false; + + // Check UNLESS clauses + foreach (Clause c in r.Clauses) + { + if (c.clauseType.Label == "UNLESS") + { + // If exception applies, return false + if (VerifyRelationship(c.clause)) + return false; + } + } + + return true; // General rule applies +} +``` + +## Emotional/Affective Causality + +### Concept + +Events cause emotional states, represented as causal relationships. + +**Pattern**: +``` +[Event] --[causes]--> [Emotion] + └── BECAUSE: [Event] --[has.property]--> [Unpleasant] +``` + +### Example: Emotional Responses + +``` +[Lost-Job] --[causes]--> [Sad] + └── BECAUSE: [Lost-Job] --[has.property]--> [Negative] + +[Won-Lottery] --[causes]--> [Happy] + └── BECAUSE: [Won-Lottery] --[has.property]--> [Positive] +``` + +**Reasoning**: +``` +Query: "Why does losing a job cause sadness?" +1. Find: [Lost-Job] --[causes]--> [Sad] +2. Follow BECAUSE: [Lost-Job] --[has.property]--> [Negative] +3. Generalize: Negative events cause sad emotions +``` + +## Spatial and Social Context + +### 1. Spatial Co-occurrence + +**Concept**: Things that exist in the same space are associated. + +``` +[Kitchen] --[contains]--> [Stove] + --[contains]--> [Refrigerator] + --[contains]--> [Sink] + +[Stove] --[co-occurs-with]--> [Refrigerator] + └── BECAUSE: [Common-Location] --[is]--> [Kitchen] +``` + +### 2. Social Context + +**Concept**: Relationships depend on social setting. + +``` +[Person] --[calls]--> [Doctor] + └── IF: [Person] --[has]--> [Illness] + +[Person] --[calls]--> [Lawyer] + └── IF: [Person] --[has]--> [Legal-Problem] +``` + +## Sensor-Monitor Mapping + +### Concept + +Sensor readings trigger conditional responses. + +**Pattern**: +``` +[Sensor-Reading] --[triggers]--> [Action] + └── IF: [Value] --[exceeds]--> [Threshold] +``` + +### Example: Temperature Control + +``` +[Temperature-Sensor] --[reads]--> [Temperature-Value] + +[Temperature-Value] --[triggers]--> [Turn-On-AC] + └── IF: [Temperature-Value] --[exceeds]--> [75°F] + +[Temperature-Value] --[triggers]--> [Turn-On-Heat] + └── IF: [Temperature-Value] --[below]--> [65°F] +``` + +**Implementation**: +```csharp +public void MonitorSensor(Thing sensor, Thing value) +{ + // Get all triggered actions + List triggers = value.Relationships.FindAll( + x => x.relType.Label == "triggers"); + + foreach (Relationship trigger in triggers) + { + // Check IF clauses + bool conditionsMet = true; + foreach (Clause c in trigger.Clauses) + { + if (c.clauseType.Label == "IF") + { + conditionsMet &= EvaluateCondition(c.clause); + } + } + + if (conditionsMet) + { + ExecuteAction(trigger.target); + } + } +} +``` + +## Routine Sequencing (Animal Behavior) + +### Concept + +Actions follow predictable sequences, modeled as chained relationships. + +``` +[Wake-Up] --[then]--> [Eat-Breakfast] +[Eat-Breakfast] --[then]--> [Brush-Teeth] +[Brush-Teeth] --[then]--> [Get-Dressed] +``` + +### Implementation: Sequential Chains + +```csharp +public List GetActionSequence(Thing startAction) +{ + List sequence = new() { startAction }; + Thing current = startAction; + + while (true) + { + // Find "then" relationship + Relationship next = current.Relationships.FindFirst( + x => x.relType.Label == "then"); + + if (next == null) break; // End of sequence + + sequence.Add(next.target); + current = next.target; + } + + return sequence; +} +``` + +### Example: Morning Routine + +``` +[Person] --[performs]--> [Morning-Routine] + +[Morning-Routine] --[starts-with]--> [Wake-Up] + +[Wake-Up] --[then]--> [Shower] +[Shower] --[then]--> [Dress] +[Dress] --[then]--> [Eat-Breakfast] +[Eat-Breakfast] --[then]--> [Leave-Home] +``` + +## Parallel Actions and Correlation + +### Concept + +Multiple actions occur simultaneously, possibly correlated. + +``` +[Event-A] --[occurs-simultaneously]--> [Event-B] + --[possibly-causes]--> [Event-C] +``` + +### Example: Correlated Behaviors + +``` +[Rain] --[correlates-with]--> [Umbrella-Use] + --[correlates-with]--> [Traffic-Increase] +``` +w +**Correlation Weight**: +```csharp +// Track co-occurrence frequency +Relationship r = uks.AddStatement("Rain", "correlates-with", "Umbrella-Use"); +r.Weight = 0.85f; // 85% correlation observed +``` + +## Unlimited Compounding + +### Concept + +Clauses can be chained indefinitely to represent arbitrarily complex logic. + +``` +R1 IF R2 UNLESS R3 BECAUSE R4 IF R5 ... +``` + +### Example: Complex Medical Diagnosis + +``` +[Patient] --[has]--> [Disease-X] + └── IF: [Patient] --[has]--> [Symptom-A] + └── IF: [Patient] --[has]--> [Symptom-B] + └── UNLESS: [Patient] --[has]--> [Symptom-C] + └── BECAUSE: [Symptom-C] --[indicates]--> [Disease-Y] + └── IF: [Test-Result] --[is]--> [Positive] +``` + +## Implementing in PyTorch/PyTorch Geometric + +### Strategy 1: Hypergraph Representation + +Use hyperedges to represent clauses (edges on edges): + +```python +import torch +from torch_geometric.data import Data + +class ClauseData: + def __init__(self): + # Node features + self.node_features = [] # Thing embeddings + + # Edge features (Relationships) + self.edge_index = [] # [source, target] pairs + self.edge_features = [] # Relationship type embeddings + + # Hyperedge features (Clauses) + self.clause_index = [] # [rel1_id, rel2_id] pairs + self.clause_types = [] # "IF", "BECAUSE", etc. + + def add_clause(self, rel1_id, clause_type, rel2_id): + self.clause_index.append([rel1_id, rel2_id]) + self.clause_types.append(clause_type) +``` + +### Strategy 2: Nested GNN for Multi-Order Relationships + +```python +class ClauseGNN(torch.nn.Module): + def __init__(self, node_dim, edge_dim, clause_dim): + super().__init__() + self.node_encoder = GCNConv(node_dim, node_dim) + self.edge_encoder = nn.Linear(edge_dim * 3, edge_dim) # src+rel+tgt + self.clause_encoder = nn.Linear(edge_dim * 2, clause_dim) + + def forward(self, x, edge_index, edge_attr, clause_index, clause_type): + # 1. Node-level propagation + x = self.node_encoder(x, edge_index) + + # 2. Edge-level embedding (relationship representation) + src_emb = x[edge_index[0]] + tgt_emb = x[edge_index[1]] + edge_emb = self.edge_encoder( + torch.cat([src_emb, edge_attr, tgt_emb], dim=-1)) + + # 3. Clause-level embedding (meta-relationship) + if clause_index.size(0) > 0: + rel1_emb = edge_emb[clause_index[:, 0]] + rel2_emb = edge_emb[clause_index[:, 1]] + clause_emb = self.clause_encoder( + torch.cat([rel1_emb, rel2_emb], dim=-1)) + return x, edge_emb, clause_emb + + return x, edge_emb, None +``` + +### Strategy 3: Rule-Based Clause Evaluation + +```python +class ClauseEvaluator: + def __init__(self, knowledge_graph): + self.kg = knowledge_graph + + def evaluate(self, relationship, context): + """ + Evaluate if a relationship holds given context + """ + # Check IF clauses + if_clauses = self.kg.get_clauses(relationship, clause_type="IF") + for clause in if_clauses: + if not self.verify_relationship(clause, context): + return False # Condition not met + + # Check UNLESS clauses + unless_clauses = self.kg.get_clauses(relationship, clause_type="UNLESS") + for clause in unless_clauses: + if self.verify_relationship(clause, context): + return False # Exception applies + + return True # All conditions satisfied + + def verify_relationship(self, relationship, context): + """ + Recursively verify relationship with clause chain + """ + # Base case: check if relationship exists in context + if relationship in context: + return True + + # Recursive case: check clauses + return self.evaluate(relationship, context) +``` + +### Strategy 4: Temporal Graph Network + +```python +class TemporalKG: + def __init__(self): + self.static_graph = nx.DiGraph() + self.temporal_edges = {} # edge -> (timestamp, ttl) + + def add_temporal_relationship(self, source, reltype, target, ttl_seconds): + edge = (source, reltype, target) + timestamp = time.time() + self.temporal_edges[edge] = (timestamp, ttl_seconds) + self.static_graph.add_edge(source, target, reltype=reltype) + + def cleanup_expired(self): + current_time = time.time() + expired = [] + + for edge, (timestamp, ttl) in self.temporal_edges.items(): + if current_time - timestamp > ttl: + expired.append(edge) + + for edge in expired: + source, reltype, target = edge + self.static_graph.remove_edge(source, target) + del self.temporal_edges[edge] +``` + +## Key Takeaways + +1. **Clauses as meta-edges**: Relationships between relationships enable conditional logic +2. **IF clauses**: Create instances to avoid modifying universal statements +3. **BECAUSE clauses**: Represent causal explanations +4. **Temporal logic**: TTL mechanism for working memory +5. **Compound patterns**: Multiple clauses create AND/OR/nested logic +6. **Exception handling**: UNLESS clauses override general rules +7. **Recursive evaluation**: Clause chains require depth-first verification +8. **Context-dependent reasoning**: Social, spatial, emotional context affects truth + +## References + +- [Relationship.cs](../UKS/Relationship.cs) - Clause implementation +- [UKS.cs](../UKS/UKS.cs) - AddClause method, TTL cleanup +- [UKS.Statement.cs](../UKS/UKS.Statement.cs) - Statement API with clause support diff --git a/user_docs/04_neural_concepts_resource_management.md b/user_docs/04_neural_concepts_resource_management.md new file mode 100644 index 0000000..4faae99 --- /dev/null +++ b/user_docs/04_neural_concepts_resource_management.md @@ -0,0 +1,799 @@ +# Neural Concepts and Resource Management in BrainSim III + +## Overview + +While BrainSim III is primarily a knowledge representation system, it incorporates several neural-inspired concepts including sparse coding, lateral inhibition, gating mechanisms, and resource management (neuron tracking and column selection). This document explores how these concepts are implemented through the UKS graph structure. + +## Sparse Coding Through Singularity + +### Concept + +In neuroscience, **sparse coding** means representing information with a small number of active neurons from a large population. BrainSim III achieves this through: + +1. **Information Singularity**: Each concept exists in exactly one location +2. **Unique Labels**: Hash table ensures O(1) lookup without redundancy +3. **Distributed Relationships**: Information spreads through edges, not nodes + +### Implementation + +**File**: [ThingLabels.cs](../UKS/ThingLabels.cs) + +```csharp +public class ThingLabels +{ + private static Dictionary thingLabels = new(); + + public static Thing GetThing(string label) + { + if (string.IsNullOrEmpty(label)) return null; + string labelLower = label.ToLower(); + + if (thingLabels.TryGetValue(labelLower, out Thing? value)) + return value; + return null; + } + + public static string AddThingLabel(string label, Thing t) + { + string labelLower = label.ToLower(); + + // Enforce singularity: one Thing per concept + if (thingLabels.ContainsKey(labelLower)) + { + if (thingLabels[labelLower] != t) + throw new Exception("Duplicate label"); + return thingLabels[labelLower].Label; + } + + thingLabels[labelLower] = t; + return label; // Preserve original case + } +} +``` + +### Benefits + +1. **Memory Efficiency**: No duplicate representations +2. **Fast Access**: O(1) lookup vs. O(n) search +3. **Consistency**: Single source of truth +4. **Sparse Activation**: Only referenced Things are "active" at query time + +### Comparison to Neural Sparse Coding + +| Neural Sparse Coding | BrainSim III | +|---------------------|--------------| +| Few active neurons | Few active Things in query | +| High-dimensional space | Large graph space | +| Energy efficient | Computationally efficient | +| Distributed representation | Distributed relationships | +| Redundancy for resilience | Multiple paths for resilience | + +## Lateral Inhibition Through Exclusivity + +### Concept + +**Lateral inhibition** in neuroscience occurs when neurons suppress their neighbors, creating winner-take-all competition. BrainSim III implements this through: + +1. **Exclusive properties**: Conflicting attributes suppress each other +2. **Weight competition**: Higher-weighted relationships win +3. **Redundancy removal**: Duplicate attributes are pruned + +### Exclusive Properties + +**File**: [UKS.cs:196-295](../UKS/UKS.cs#L196-L295) + +```csharp +private bool RelationshipsAreExclusive(Relationship r1, Relationship r2) +{ + // Check if targets have common parent with "isExclusive" property + if (r1.relType == r2.relType && r1.target != r2.target) + { + List commonParents = FindCommonParents(r1.target, r2.target); + foreach (Thing parent in commonParents) + { + if (parent.HasProperty("isExclusive")) + return true; // Only one can be true + } + } + + // Check for negation conflicts + IList r1Attrs = r1.relType.GetAttributes(); + IList r2Attrs = r2.relType.GetAttributes(); + Thing r1Not = r1Attrs.FindFirst(x => x.Label == "not" || x.Label == "no"); + Thing r2Not = r2Attrs.FindFirst(x => x.Label == "not" || x.Label == "no"); + + if ((r1Not != null && r2Not == null) || (r1Not == null && r2Not != null)) + { + if (r1.target == r2.target) + return true; // "can fly" vs "cannot fly" + } + + return false; +} +``` + +### Example: Color Exclusivity + +**Setup**: +```csharp +Thing color = uks.GetOrAddThing("Color", "Attribute"); +color.AddRelationship("isExclusive", "hasProperty"); + +Thing red = uks.GetOrAddThing("Red", color); +Thing blue = uks.GetOrAddThing("Blue", color); +Thing green = uks.GetOrAddThing("Green", color); +``` + +**Usage**: +``` +[Ball] --[has.color]--> [Red] (Weight: 0.9) +[Ball] --[has.color]--> [Blue] (Weight: 0.6) ← Suppressed + +Result: Ball is Red (Blue relationship has lower weight and conflicts) +``` + +### Conflict Resolution Algorithm + +```csharp +public List ResolveConflicts(List relationships) +{ + List resolved = new(); + + foreach (Relationship r1 in relationships) + { + bool suppressed = false; + + foreach (Relationship r2 in relationships) + { + if (r1 == r2) continue; + + // Check if they conflict + if (RelationshipsAreExclusive(r1, r2)) + { + // Higher weight wins + if (r2.Weight > r1.Weight) + { + suppressed = true; + break; + } + } + } + + if (!suppressed) + resolved.Add(r1); + } + + return resolved; +} +``` + +## Gating Mechanisms + +### Concept + +**Gating** controls information flow, determining what gets processed or propagated. BrainSim III implements gating through: + +1. **Conditional clauses**: IF/UNLESS act as gates +2. **Weight thresholds**: Low-weight relationships are gated out +3. **Property-based filtering**: hasProperty gates inheritance +4. **Transience**: TTL gates temporal information + +### IF Clause as Gate + +``` +[Action] --[triggers]--> [Response] + └── IF: [Condition] --[is]--> [True] + +Gate open: Condition is true → Response triggered +Gate closed: Condition is false → Response blocked +``` + +**Implementation**: +```csharp +public bool IsGateOpen(Relationship r) +{ + // Check IF clauses (gates) + foreach (Clause c in r.Clauses) + { + if (c.clauseType.Label == "IF") + { + // Gate closed if condition not met + if (!VerifyCondition(c.clause)) + return false; + } + } + return true; // All gates open +} +``` + +### Weight Threshold Gating + +**File**: [ModuleAttributeBubble.cs:167-174](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs#L167-L174) + +```csharp +float newWeight = currentWeight + targetWeight; + +if (newWeight < 0.5) // Threshold gate +{ + // Below threshold: gate closed, remove relationship + if (r != null) + { + t.RemoveRelationship(r); + debugString += $"Removed {r.ToString()} \n"; + } +} +else +{ + // Above threshold: gate open, keep/add relationship + r = t.AddRelationship(rr.target, rr.relType); + r.Weight = newWeight; +} +``` + +### Property-Based Gating + +Certain properties gate whether a relationship is inherited or transitive: + +``` +[has-child] --[hasProperty]--> [isTransitive] ← Gates recursive following + +Query: "What does X have?" +- If relType has isTransitive: Follow inheritance chain +- If not: Only direct relationships +``` + +## Tracking Free/In-Use Things (Neuron Allocation) + +### Concept + +Similar to how neural circuits track available neurons, BrainSim III tracks Thing usage through: + +1. **useCount**: How many times a Thing has been accessed +2. **lastFiredTime**: When it was last activated +3. **Relationship hits/misses**: Usage statistics + +### Implementation + +**File**: [Thing.cs:65-66](../UKS/Thing.cs#L65-L66) + +```csharp +public int useCount = 0; +public DateTime lastFiredTime = new(); + +public void SetFired() +{ + lastFiredTime = DateTime.Now; + useCount++; +} +``` + +**File**: [Relationship.cs:158-167](../UKS/Relationship.cs#L158-L167) + +```csharp +private int hits = 0; // Successful uses +private int misses = 0; // Failed uses + +public int Hits { get => hits; set => hits = value; } +public int Misses { get => misses; set => misses = value; } + +public float Value // Computed confidence +{ + get + { + float retVal = Weight; + if (Hits != 0 && Misses != 0) + { + retVal = Hits / (Misses == 0 ? 0.1f : Misses); + } + return retVal; + } +} +``` + +### Usage Tracking Example + +```csharp +// Query for a Thing +Thing dog = uks.Labeled("Dog"); +dog.SetFired(); // Mark as accessed + +// Query a relationship +Relationship r = dog.Relationships.FindFirst(x => x.relType.Label == "has"); +r.Hits++; // Successful query +r.Fire(); // Update lastUsed timestamp + +// Failed query +Relationship r2 = dog.Relationships.FindFirst(x => x.relType.Label == "unknown"); +if (r2 == null) +{ + foreach (Relationship rel in dog.Relationships) + rel.Misses++; // All relationships "missed" +} +``` + +**File**: [Thing.cs:189-191](../UKS/Thing.cs#L189-L191) + +```csharp +public IList Relationships +{ + get + { + lock (relationships) + { + // Automatically increment misses on access + foreach (Relationship r in relationships) + r.Misses++; + return new List(relationships.AsReadOnly()); + } + } +} +``` + +### Resource Reclamation + +Things with low usage could be pruned (not currently implemented, but framework exists): + +```csharp +public void PruneUnusedThings(TimeSpan inactivityThreshold) +{ + DateTime cutoff = DateTime.Now - inactivityThreshold; + List toRemove = new(); + + foreach (Thing t in uks.UKSList) + { + if (t.lastFiredTime < cutoff && t.useCount < 5) + { + toRemove.Add(t); + } + } + + foreach (Thing t in toRemove) + { + uks.DeleteThing(t); + } +} +``` + +## Selecting Columns to Use + +### Concept + +In cortical columns, specific columns are selected for processing. BrainSim III achieves similar selection through: + +1. **Dynamic instance creation**: Auto-numbered Things act as "columns" +2. **Instance tracking**: Finding the next available instance +3. **Context-specific selection**: Choosing the right instance for a situation + +### Dynamic Instance Creation + +**File**: [UKS.cs:511-527](../UKS/UKS.cs#L511-L527) + +```csharp +public Thing GetOrAddThing(string label, object parent = null, Thing source = null) +{ + if (label.EndsWith("*")) + { + string baseLabel = label.Substring(0, label.Length - 1); + Thing newParent = ThingLabels.GetThing(baseLabel); + + // Find next available instance number + if (source != null) + { + int digit = 0; + while (source.Relationships.FindFirst( + x => x.reltype.Label == baseLabel + digit) != null) + { + digit++; + } + + // Check if this instance already exists + Thing labeled = ThingLabels.GetThing(baseLabel + digit); + if (labeled != null) + return labeled; // Reuse existing "column" + } + + if (newParent == null) + newParent = AddThing(baseLabel, correctParent); + correctParent = newParent; + } + + thingToReturn = AddThing(label, correctParent); + return thingToReturn; +} +``` + +### Example: Column Allocation + +```csharp +// Create base "column type" +Thing bird = uks.GetOrAddThing("Bird", "Animal"); + +// Allocate specific "columns" (instances) +Thing bird0 = uks.GetOrAddThing("Bird*"); // Creates "Bird0" +Thing bird1 = uks.GetOrAddThing("Bird*"); // Creates "Bird1" +Thing bird2 = uks.GetOrAddThing("Bird*"); // Creates "Bird2" + +// Each instance can have different properties +bird0.AddRelationship("Blue", "has.color"); +bird1.AddRelationship("Red", "has.color"); +bird2.AddRelationship("Green", "has.color"); + +// All share base class properties +foreach (Thing instance in bird.Children) +{ + // Inherits from Bird: can fly, has feathers, etc. +} +``` + +### Context-Based Column Selection + +```csharp +public Thing SelectAppropriateInstance(Thing baseClass, List requiredAttributes) +{ + // Find instance matching context + foreach (Thing instance in baseClass.Children) + { + bool matches = true; + foreach (Thing attr in requiredAttributes) + { + if (instance.Relationships.FindFirst(x => x.target == attr) == null) + { + matches = false; + break; + } + } + + if (matches) + return instance; // Found appropriate "column" + } + + // No match: allocate new instance + Thing newInstance = uks.GetOrAddThing(baseClass.Label + "*"); + foreach (Thing attr in requiredAttributes) + { + newInstance.AddRelationship(attr, "has"); + } + return newInstance; +} +``` + +## In/Out Neurons (Relationship Direction) + +### Concept + +Neurons have input and output connections. BrainSim III models this through: + +1. **relationships**: Outgoing edges (outputs) +2. **relationshipsFrom**: Incoming edges (inputs) +3. **relationshipsAsType**: Where this Thing is the connection type + +### Implementation + +**File**: [Thing.cs:38-61](../UKS/Thing.cs#L38-L61) + +```csharp +private List relationships = new(); // Output connections +private List relationshipsFrom = new(); // Input connections +private List relationshipsAsType = new(); // Type connections + +// Safe "input neuron" access +public IList RelationshipsFrom +{ + get + { + lock (relationshipsFrom) + { + return new List(relationshipsFrom.AsReadOnly()); + } + } +} + +// Safe "output neuron" access +public IList Relationships +{ + get + { + lock (relationships) + { + foreach (Relationship r in relationships) + r.Misses++; // Track access + return new List(relationships.AsReadOnly()); + } + } +} +``` + +### Bidirectional Navigation + +```csharp +// Forward propagation (outputs) +public List GetOutputs(Thing t, Thing relType) +{ + List outputs = new(); + foreach (Relationship r in t.Relationships) + { + if (r.relType == relType) + outputs.Add(r.target); + } + return outputs; +} + +// Backward propagation (inputs) +public List GetInputs(Thing t, Thing relType) +{ + List inputs = new(); + foreach (Relationship r in t.RelationshipsFrom) + { + if (r.relType == relType) + inputs.Add(r.source); + } + return inputs; +} +``` + +### Example: Causal Chain + +``` +[Rain] --[causes]--> [Wet-Ground] +[Wet-Ground] --[causes]--> [Slippery-Surface] + +Query: "What causes Wet-Ground?" +Process: +1. Access Wet-Ground.RelationshipsFrom (inputs) +2. Filter by relType "causes" +3. Result: Rain + +Query: "What does Wet-Ground cause?" +Process: +1. Access Wet-Ground.Relationships (outputs) +2. Filter by relType "causes" +3. Result: Slippery-Surface +``` + +## Cortical Columns (Hierarchical Thing Groups) + +### Concept + +Cortical columns are vertical structures processing related information. BrainSim III creates analogous structures through: + +1. **Hierarchical Thing groupings**: Parent-child trees +2. **Shared attribute inheritance**: Common properties bubble up +3. **Specialized instances**: Children with unique properties + +### Example: Animal Hierarchy as Cortical Structure + +``` +[Animal] ← "Column root" + | + ├─ [Mammal] + │ ├─ [Dog] + │ │ ├─ [Retriever] ← "Sub-column" + │ │ │ ├─ [Fido0] (instance) + │ │ │ └─ [Fido1] (instance) + │ │ └─ [Poodle] ← "Sub-column" + │ │ ├─ [Rex0] (instance) + │ │ └─ [Rex1] (instance) + │ └─ [Cat] + │ ├─ [Siamese] + │ └─ [Persian] + └─ [Bird] + ├─ [Sparrow] + └─ [Eagle] +``` + +Each level represents a cortical layer: +- **Root**: Broadest category +- **Intermediate**: Specialized groups +- **Leaf**: Specific instances + +### Column Activation Pattern + +```csharp +public void ActivateColumn(Thing root, Thing stimulus) +{ + // Activate root + root.SetFired(); + + // Propagate down to matching children + foreach (Thing child in root.Children) + { + // Check if stimulus matches this sub-column + if (MatchesStimulus(child, stimulus)) + { + child.SetFired(); + ActivateColumn(child, stimulus); // Recursive descent + } + } +} + +private bool MatchesStimulus(Thing thing, Thing stimulus) +{ + // Check if thing has attributes matching stimulus + foreach (Relationship r in thing.Relationships) + { + if (r.target == stimulus) + return true; + } + return false; +} +``` + +## Redundancy and Resilience + +### Concept + +Neural systems are resilient due to redundant pathways. BrainSim III achieves this through: + +1. **Multiple inheritance**: Multiple paths to information +2. **Distributed representation**: Information in structure, not single node +3. **Relationship backup**: Same fact represented multiple ways + +### Example: Redundant Knowledge Paths + +``` +Path 1: [Fido] --[is-a]--> [Dog] --[is-a]--> [Animal] +Path 2: [Fido] --[is-a]--> [Pet] --[is-a]--> [Animal] +Path 3: [Fido] --[has.owner]--> [John] --[has.pet]--> [Animal-Type] + +Query: "Is Fido an animal?" +Can be answered via: +- Direct is-a chain (Path 1) +- Alternative is-a chain (Path 2) +- Inference from ownership (Path 3) +``` + +### Resilience to Node Loss + +```csharp +public bool CanReachTarget(Thing source, Thing target, HashSet blockedNodes) +{ + if (source == target) return true; + if (blockedNodes.Contains(source)) return false; + + HashSet visited = new() { source }; + Queue queue = new(); + queue.Enqueue(source); + + while (queue.Count > 0) + { + Thing current = queue.Dequeue(); + + // Try all outgoing relationships + foreach (Relationship r in current.Relationships) + { + Thing next = r.target; + if (blockedNodes.Contains(next)) continue; + if (next == target) return true; + + if (!visited.Contains(next)) + { + visited.Add(next); + queue.Enqueue(next); + } + } + } + + return false; // No path found +} +``` + +Even if intermediate nodes are blocked/deleted, multiple paths provide resilience. + +## Implementing in PyTorch/PyTorch Geometric + +### Strategy 1: Sparse Graph Attention + +```python +import torch +from torch_geometric.nn import GATConv + +class SparseAttentionKG(torch.nn.Module): + def __init__(self, in_channels, out_channels): + super().__init__() + self.attention = GATConv(in_channels, out_channels, heads=8, dropout=0.6) + + def forward(self, x, edge_index): + # Attention mechanism acts as lateral inhibition + # High attention weights suppress low attention neighbors + return self.attention(x, edge_index) +``` + +### Strategy 2: Gating with Neural Networks + +```python +class GatedRelationship(torch.nn.Module): + def __init__(self, feature_dim): + super().__init__() + self.gate = nn.Sequential( + nn.Linear(feature_dim * 2, feature_dim), + nn.Sigmoid() # Gate value [0, 1] + ) + + def forward(self, source_features, target_features, condition_features): + # Compute gate value + combined = torch.cat([source_features, condition_features], dim=-1) + gate_value = self.gate(combined) + + # Apply gate to target + gated_target = gate_value * target_features + return gated_target +``` + +### Strategy 3: Dynamic Instance Pool + +```python +class InstancePool: + def __init__(self, base_class, max_instances=100): + self.base_class = base_class + self.instances = [] + self.available = list(range(max_instances)) + self.in_use = {} + + def allocate(self, attributes): + """Allocate an instance (column) with given attributes""" + if not self.available: + raise RuntimeError("No available instances") + + instance_id = self.available.pop(0) + self.instances.append({ + 'id': instance_id, + 'base_class': self.base_class, + 'attributes': attributes, + 'use_count': 0, + 'last_used': time.time() + }) + self.in_use[instance_id] = len(self.instances) - 1 + return instance_id + + def release(self, instance_id): + """Release instance back to pool""" + if instance_id in self.in_use: + idx = self.in_use[instance_id] + del self.in_use[instance_id] + self.available.append(instance_id) +``` + +### Strategy 4: Usage Tracking in PyG + +```python +class UsageTracker: + def __init__(self, num_nodes, num_edges): + self.node_use_count = torch.zeros(num_nodes, dtype=torch.long) + self.node_last_fired = torch.zeros(num_nodes, dtype=torch.float32) + self.edge_hits = torch.zeros(num_edges, dtype=torch.long) + self.edge_misses = torch.zeros(num_edges, dtype=torch.long) + + def fire_node(self, node_id): + self.node_use_count[node_id] += 1 + self.node_last_fired[node_id] = time.time() + + def hit_edge(self, edge_id): + self.edge_hits[edge_id] += 1 + + def miss_edge(self, edge_id): + self.edge_misses[edge_id] += 1 + + def get_edge_confidence(self, edge_id): + hits = self.edge_hits[edge_id].float() + misses = self.edge_misses[edge_id].float() + return hits / (misses + 1e-6) # Confidence score +``` + +## Key Takeaways + +1. **Sparse coding**: Unique labels ensure singular representation +2. **Lateral inhibition**: Exclusive properties create competition +3. **Gating**: IF/UNLESS clauses, weight thresholds control flow +4. **Resource tracking**: useCount, lastFiredTime monitor usage +5. **Column selection**: Dynamic instances with auto-numbering +6. **In/Out neurons**: Bidirectional relationship navigation +7. **Cortical columns**: Hierarchical Thing groups +8. **Redundancy**: Multiple paths provide resilience + +## References + +- [Thing.cs](../UKS/Thing.cs) - Usage tracking, relationship navigation +- [Relationship.cs](../UKS/Relationship.cs) - Hits/misses, weight computation +- [UKS.cs](../UKS/UKS.cs) - Conflict detection, instance creation +- [ThingLabels.cs](../UKS/ThingLabels.cs) - Sparse label management +- [ModuleAttributeBubble.cs](../BrainSimulator/Modules/Agents/ModuleAttributeBubble.cs) - Weight-based gating