@elizaos/plugin-action-bench 1.4.3 → 1.4.4

package/README.md

@@ -1,8 +1,8 @@
 # plugin-action-bench
 
-Action calling benchmark plugins for ElizaOS v2, featuring multiverse mathematics where operations behave differently based on dimensional constants. Designed to test AI agents' ability to handle context-dependent mathematics, unknown operational behaviors, and complex state management across dimensional boundaries.
+Action calling benchmark plugins for ElizaOS v2, featuring typewriter actions, multiverse mathematics with dimensional constants, and relational data management. Designed to test AI agents' ability to handle action chaining, context-dependent operations, and complex entity-relationship graphs.
 
-> **🎛️ Environment Control**: Use `TYPEWRITER_ENABLED=false` or `MULTIVERSE_MATH_ENABLED=false` to selectively disable benchmark sets. See [Environment Variable Configuration](#environment-variable-configuration) for details.
+> **🎛️ Environment Control**: Use `TYPEWRITER_ENABLED=false`, `MULTIVERSE_MATH_ENABLED=false`, or `RELATIONAL_DATA_ENABLED=false` to selectively disable benchmark sets. See [Environment Variable Configuration](#environment-variable-configuration) for details.
 
 ## Features
 
@@ -73,16 +73,50 @@ Square root variations:
 - **MATH_CLEAR**: Reset all buffers
 - **TRANSFER_TO_INPUT**: Move accumulator to input buffer
 
+### 🔗 Relational Data Operations
+Entity-relationship graph management for testing complex data operations:
+
+#### Entity Management
+- **CREATE_ENTITY**: Create entities with types (person, company, product, etc.)
+- **SELECT_ENTITY**: Select an entity as the current focus
+- **DELETE_ENTITY**: Delete entity and all its relationships
+- **SET_ATTRIBUTE**: Add/update attributes on entities
+
+#### Relationship Management
+- **CREATE_RELATIONSHIP**: Link entities with typed relationships
+  - Types: parent_child, sibling, friend, employment, ownership, management, partnership, membership, location, assignment
+
+#### Query Operations
+- **QUERY_ENTITIES**: Find entities by type or attribute values
+- **QUERY_RELATIONSHIPS**: Find relationships by type or entity
+- **FIND_PATH**: Find shortest path between two entities
+- **COUNT_STATISTICS**: Get graph statistics (entity/relationship counts)
+
+#### Utility Operations
+- **CLEAR_GRAPH**: Reset the entire entity-relationship graph
+
 ## State Management
 
 The plugin maintains a sophisticated state system:
+
+### Typewriter State
+- **typedText**: Accumulation buffer for typed characters
+
+### Multiverse Math State
 - **accumulator**: Main calculation result storage
 - **inputBuffer**: Temporary number input storage
 - **memory**: Persistent value storage
-- **history**: Operation history tracking with explanations
-- **typedText**: Typewriter accumulation buffer
 - **dimension**: Current dimensional constant affecting operations
-- **lastOperation**: Track the most recent operation performed
+- **history**: Operation history tracking with explanations
+
+### Relational Data State
+- **entities**: Collection of created entities with attributes
+- **relationships**: Collection of relationships between entities
+- **currentEntity**: Currently selected entity for operations
+- **queryResults**: Results from recent queries
+
+### Global State
+- **lastOperation**: Track the most recent operation performed across all benchmarks
 
 ## Usage
 
@@ -108,7 +142,8 @@ console.log("Benchmark configuration:", benchmarkConfig);
 // {
 //   typewriterEnabled: true,
 //   multiverseMathEnabled: true,
-//   totalActionsLoaded: 48
+//   relationalDataEnabled: true,
+//   totalActionsLoaded: 58
 // }
 ```
 
@@ -122,6 +157,7 @@ The plugin supports granular control over which benchmark actions are loaded thr
 |----------|---------|-------------|
 | `TYPEWRITER_ENABLED` | `true` | Controls loading of typewriter actions (A-Z) |
 | `MULTIVERSE_MATH_ENABLED` | `true` | Controls loading of multiverse math operations |
+| `RELATIONAL_DATA_ENABLED` | `true` | Controls loading of relational data operations |
 
 ### Examples
 
@@ -130,13 +166,16 @@ The plugin supports granular control over which benchmark actions are loaded thr
 npm start
 
 # Only load typewriter actions
-MULTIVERSE_MATH_ENABLED=false npm start
+MULTIVERSE_MATH_ENABLED=false RELATIONAL_DATA_ENABLED=false npm start
 
 # Only load multiverse math actions
-TYPEWRITER_ENABLED=false npm start
+TYPEWRITER_ENABLED=false RELATIONAL_DATA_ENABLED=false npm start
 
-# Disable all benchmarks (useful for production)
+# Only load relational data actions
 TYPEWRITER_ENABLED=false MULTIVERSE_MATH_ENABLED=false npm start
+
+# Disable all benchmarks (useful for production)
+TYPEWRITER_ENABLED=false MULTIVERSE_MATH_ENABLED=false RELATIONAL_DATA_ENABLED=false npm start
 ```
 
 ### .env File Configuration
@@ -147,10 +186,12 @@ You can also configure these in your `.env` file:
 # Enable/disable specific benchmarks
 TYPEWRITER_ENABLED=true
 MULTIVERSE_MATH_ENABLED=true
+RELATIONAL_DATA_ENABLED=true
 
 # Example: Only enable typewriter for focused testing
 # TYPEWRITER_ENABLED=true
 # MULTIVERSE_MATH_ENABLED=false
+# RELATIONAL_DATA_ENABLED=false
 ```
 
 ### Runtime Feedback
@@ -160,7 +201,8 @@ The plugin provides console output to confirm which benchmarks are loaded:
 ```
 [plugin-action-bench] Typewriter actions enabled
 [plugin-action-bench] Multiverse math actions enabled
-[plugin-action-bench] Total actions loaded: 48
+[plugin-action-bench] Relational data actions enabled
+[plugin-action-bench] Total actions loaded: 58
 ```
 
 Or when disabled:
@@ -168,7 +210,8 @@ Or when disabled:
 ```
 [plugin-action-bench] Typewriter actions disabled via TYPEWRITER_ENABLED=false
 [plugin-action-bench] Multiverse math actions enabled
-[plugin-action-bench] Total actions loaded: 22
+[plugin-action-bench] Relational data actions enabled
+[plugin-action-bench] Total actions loaded: 32
 ```
 
 ### Why Use Environment Variables?
@@ -236,6 +279,30 @@ Agent: Must understand to set chaos dimension and apply MULTIVERSE_ADD
 Result: Deterministic chaos factor added based on seed generation
 ```
 
+### Relational Data Test
+Test entity and relationship management:
+```
+User: "Create person named Alice, create company named TechCorp, create employment relationship"
+Agent: Uses CREATE_ENTITY, CREATE_ENTITY, CREATE_RELATIONSHIP
+Result: Graph with Alice → (employment) → TechCorp
+```
+
+### Complex Graph Query Test
+Test graph traversal and querying:
+```
+User: "Create entities Bob and Carol, make them siblings, find path between them"
+Agent: Creates entities, establishes sibling relationship, finds connection path
+Result: Bob → (sibling) → Carol
+```
+
+### Attribute Management Test
+Test entity attribute handling:
+```
+User: "Create person John, set age 30, set role manager, query person entities"
+Agent: Uses CREATE_ENTITY, SET_ATTRIBUTE (×2), QUERY_ENTITIES
+Result: John with {age: 30, role: "manager"}
+```
+
 ## Development
 
 This plugin is part of the ElizaOS ecosystem and follows the standard plugin architecture.