Action Selection Knob Building

[K1rubel]

This PR implements the action-selection knob-building sub-system from C++ MOSES into MeTTa. It enables representation building for action sequences and conditional behaviors, decorates them with Action Subtree Knobs (ASKs).

Description

1. Domain Modeling & Operator Classification

• Action Classification: Classified structural action operators (such as and_seq, action_bool_if, or_seq, seq_exec, action_while, etc.) and distinguished them from user-defined domain actions.

• Untyped Validation: Introduced helper functions like isDomainAction / isBuiltinAction to treat caller-supplied action lists as the source of truth for primitive actions in MeTTa's untyped environment.

2. Action Subtree Knobs (ASK) Representation (lsk.metta)
   Designed and registered two constructors for wrapping action subtrees into discrete knobs:

• Action-Subtree ASK (actionSubtreeKnob): Holds a list of alternate action permutations. Multiplicity is set to $N + 1$ (where index 0 represents the absent choice, and indices 1..N correspond to selected permutations).

• Simple-Action ASK (simpleActionSubtreeKnob): Wraps a single built-in action subtree. Multiplicity is set to $2$ (index 0 is absent, index 1 is present).

3. Stochastic Representation Building (build-action.metta)
   Implemented the C++ recursive knob-building algorithm (build_knobs::build_action) with the probability threshold $p = 80:

• Sequences (and_seq):

• Root sequence blocks are decorated with action choice knobs (80% probability).

  • Existing sequence children are mapped recursively: built-in actions are wrapped in simple toggle knobs (20% probability) or sequence wrapper nodes (80% probability).

  • An empty action sequence wrapper is appended at the end of the sequence block with a 20% probability.

• Conditionals (action_bool_if):

  • Traverses the conditional branches while skipping the first child (the perception condition).
  • Recursively processes the action branches, wrapping built-in action branches in sequence nodes.

4. Sampling & Permutations

• Ordered Pair Mapping: Implemented sampleActionPerms and actionPairFromIndex to sample from the ordered action-pair space of size $N \times (N - 1)$ using lazyRandomSelector.

• Conditional Permutations: Paired random perceptions with action choices to produce conditional permutation blocks of the format: (action_bool_if $perception $actA $actB).

5. Candidate Tree Unrolling (appendToASK)
   Extended the appendTo dispatcher inside lsk.metta to support unrolling of action selection knobs during candidate scoring:

• Toggle Knobs (Simple-Action): Setting 0 prunes the branch; setting 1 appends the subtree and continues recursive candidate unrolling down the target path.

• Choice Knobs (Action-Subtree): Setting 0 prunes the branch; settings 1..N append the selected permutation and stop recursion at that node.

6. Pre and Post-Processing Passes

• Canonization (actionCanonize): Ensures sequence uniformity by wrapping non-sequential roots under a default and_seq node before knob building.

• Pruning (actionCleanup): Traverses the tree bottom-up (post-order) and removes childless structural operators (and_seq, or_seq, seq_exec), replacing them with null vertices.

7. Entry Point Integration (build-knobs.metta)
   Wired the action path into the unified buildKnobs entry point:

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have added tests to cover my changes.
• All new and existing tests passed.

To Follow this

Frame the game strategy evolution as an action selection problem and use action selection operators to evolve a game strategy.