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) 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 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 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