Implement XIC v2 control flow with IF, MATCH, LOOP operations
PHASE A: Safe predicate evaluator (glyphos/control/predicate.py) - AST-based safe expression evaluation - Supports comparisons, boolean ops, attribute access - Helper function: dominant_contains() - Protected against code injection attacks PHASE B: XICContext queue helpers - enqueue_chain(label) for FIFO chain scheduling - pop_next_chain() to get next scheduled chain - jump_to(label) for immediate destination changes PHASE C: Control flow operations (xic_ops.py) - op_IF: Conditional branching with optional else - op_MATCH: Pattern matching against fused fields - op_LOOP: Iterative execution with guardrails - Added to OP_TABLE for operation dispatch PHASE D: Execution loop enhancement (xic_vm.py) - Chain queue scheduling with label matching - Total steps tracking for guardrail enforcement - max_total_steps limit across all operations - Graceful execution stop on guardrail trigger PHASE E: Comprehensive test suite (tests/test_control_flow.py) - 14 unit tests covering all operations - Predicate evaluator tests - IF/MATCH/LOOP operation tests - Queue helper and guardrail tests - All tests passing (14/14) PHASE F: Example programs - demo_control_flow_if.gx.json: IF branching example - demo_control_flow_loop.gx.json: LOOP iteration example PHASE G: Complete documentation - XIC_V2_CONTROL_FLOW_SUMMARY.md: Technical guide - XIC_V2_QUICK_REFERENCE.md: Developer quick reference - FedMart UI and integration documentation Integration points: - FedMart telemetry captures control flow steps - UI dashboard displays control branching - Symbolic pipeline predicate evaluation - 100% backward compatible with XIC v1.5 Test results: 36/36 passing (14 control flow + 12 FedMart + 10 UI) Status: Production ready
This commit is contained in:
GlyphRunner System
@@ -0,0 +1,220 @@
|
||||
# XIC v2 Control Flow - Quick Reference
|
||||
|
||||
## Operations Summary
|
||||
|
||||
### IF - Conditional Branching
|
||||
```
|
||||
IF <predicate> <then_label> [<else_label>]
|
||||
```
|
||||
**What it does**: Evaluates a predicate and branches to different chains
|
||||
**When to use**: Decision points based on resonance scores, glyph presence, etc.
|
||||
|
||||
```json
|
||||
{"op": "IF", "args": ["fused.global_resonance_score > 0.8", "analysis_deep", "analysis_simple"]}
|
||||
```
|
||||
|
||||
### MATCH - Pattern Matching
|
||||
```
|
||||
MATCH <path> <pattern> <then_label>
|
||||
```
|
||||
**What it does**: Checks if a pattern matches a fused symbol field
|
||||
**When to use**: Looking for specific glyphs in resonance map
|
||||
|
||||
```json
|
||||
{"op": "MATCH", "args": ["fused.glyph_ids", "glyph://entropy", "entropy_found"]}
|
||||
```
|
||||
|
||||
### LOOP - Iterative Execution
|
||||
```
|
||||
LOOP <predicate> <body_label> [max_iter]
|
||||
```
|
||||
**What it does**: Repeatedly runs a chain while predicate is true
|
||||
**When to use**: Iterative refinement, convergence detection
|
||||
|
||||
```json
|
||||
{"op": "LOOP", "args": ["fused.global_resonance_score > 0.6", "refine_step", 5]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Predicate Syntax
|
||||
|
||||
### Fields
|
||||
Access fused symbol fields with dot notation:
|
||||
```
|
||||
fused.global_resonance_score # float 0.0-1.0
|
||||
fused.glyph_ids # list of strings
|
||||
fused.glyph_count # integer
|
||||
```
|
||||
|
||||
### Operators
|
||||
```
|
||||
> Greater than
|
||||
< Less than
|
||||
>= Greater or equal
|
||||
<= Less or equal
|
||||
== Equal
|
||||
!= Not equal
|
||||
and Boolean AND
|
||||
or Boolean OR
|
||||
not Boolean NOT
|
||||
```
|
||||
|
||||
### Examples
|
||||
```
|
||||
fused.global_resonance_score > 0.8
|
||||
fused.global_resonance_score > 0.8 and fused.glyph_count > 1
|
||||
fused.global_resonance_score <= 0.3 or fused.glyph_count < 2
|
||||
not (fused.global_resonance_score < 0.5)
|
||||
```
|
||||
|
||||
### Helper Functions
|
||||
```
|
||||
dominant_contains('glyph://id') # Check if glyph in dominant list
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
dominant_contains('glyph://entropy')
|
||||
dominant_contains('glyph://compression') and fused.global_resonance_score > 0.7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Program Example
|
||||
|
||||
```json
|
||||
{
|
||||
"magic": "GXIC1",
|
||||
"version": 1,
|
||||
"entrypoint": "main",
|
||||
"symbols": {
|
||||
"main": 0,
|
||||
"loop_body": 7,
|
||||
"high_path": 11,
|
||||
"low_path": 14,
|
||||
"end": 16
|
||||
},
|
||||
"instructions": [
|
||||
{"op": "SET_MODE", "args": ["symbolic"]},
|
||||
{"op": "SET_CONTEXT", "args": ["domain", "analysis"]},
|
||||
{"op": "PUSH_GLYPH_CONTEXT", "args": ["glyph://a"]},
|
||||
{"op": "PUSH_GLYPH_CONTEXT", "args": ["glyph://b"]},
|
||||
|
||||
{"op": "LOOP", "args": ["fused.global_resonance_score > 0.5", "loop_body", 3]},
|
||||
|
||||
{"op": "CHAIN", "args": ["loop_body"]},
|
||||
{"op": "RUN_PROMPT", "args": ["Refine the analysis"]},
|
||||
|
||||
{"op": "IF", "args": ["fused.global_resonance_score > 0.8", "high_path", "low_path"]},
|
||||
|
||||
{"op": "CHAIN", "args": ["high_path"]},
|
||||
{"op": "LOG", "args": ["High resonance detected"]},
|
||||
{"op": "RUN_PROMPT", "args": ["Detailed analysis"]},
|
||||
{"op": "CHAIN", "args": ["end"]},
|
||||
|
||||
{"op": "CHAIN", "args": ["low_path"]},
|
||||
{"op": "LOG", "args": ["Lower resonance - trying different approach"]},
|
||||
{"op": "RUN_PROMPT", "args": ["Alternative analysis"]},
|
||||
{"op": "CHAIN", "args": ["end"]},
|
||||
|
||||
{"op": "CHAIN", "args": ["end"]},
|
||||
{"op": "LOG", "args": ["Control flow complete"]}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
Set limits with `SET_PARAM`:
|
||||
|
||||
```json
|
||||
{"op": "SET_PARAM", "args": ["max_loop_iterations", 5]}
|
||||
{"op": "SET_PARAM", "args": ["max_total_steps", 100]}
|
||||
```
|
||||
|
||||
**Default Values:**
|
||||
- `max_loop_iterations`: 50
|
||||
- `max_total_steps`: 1000
|
||||
|
||||
---
|
||||
|
||||
## Testing Your Control Flow
|
||||
|
||||
```python
|
||||
from xic_loader import XICProgram
|
||||
from xic_vm import run_xic_program
|
||||
|
||||
# Load your program
|
||||
prog = XICProgram.from_json_file("your_program.gx.json")
|
||||
|
||||
# Execute
|
||||
ctx = run_xic_program(prog)
|
||||
|
||||
# Check results
|
||||
print(ctx._state.get("control_steps")) # Control decisions made
|
||||
print(ctx._state.get("guardrails")) # Guardrails triggered
|
||||
print(ctx._state.get("symbolic_steps")) # All execution steps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Chain 'xyz' not found"
|
||||
- Make sure you have a `CHAIN` instruction with the label name
|
||||
- Check spelling exactly matches
|
||||
|
||||
### "Predicate evaluation error"
|
||||
- Check syntax: `fused.field_name` (not `fused['field_name']`)
|
||||
- Verify field exists in fused symbol
|
||||
- Test with simpler predicate first
|
||||
|
||||
### "Guardrail triggered"
|
||||
- Loop exceeded max iterations: increase `max_loop_iterations`
|
||||
- Total steps exceeded: increase `max_total_steps`
|
||||
- Check predicate doesn't always evaluate true
|
||||
|
||||
### Control flow not executing
|
||||
- Verify `CHAIN` labels match between ops and chain names
|
||||
- Check execution with `ctx._state["symbolic_steps"]`
|
||||
- Enable `LOG` ops to trace execution path
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. **Keep predicates simple** - Complex boolean logic slows evaluation
|
||||
2. **Set reasonable loop limits** - High max_loop_iterations can timeout
|
||||
3. **Use MATCH for frequent checks** - Simpler than IF with complex predicates
|
||||
4. **Monitor total_steps** - Long programs may hit max_total_steps
|
||||
|
||||
---
|
||||
|
||||
## Integration with FedMart
|
||||
|
||||
Control flow steps automatically:
|
||||
- Appear in telemetry events
|
||||
- Display in dashboard timeline
|
||||
- Contribute to symbolic steps tracking
|
||||
- Trigger guardrail alerts when limits hit
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review example programs:
|
||||
- `programs/demo_control_flow_if.gx.json`
|
||||
- `programs/demo_control_flow_loop.gx.json`
|
||||
|
||||
2. Check test suite:
|
||||
- `tests/test_control_flow.py`
|
||||
|
||||
3. Read full documentation:
|
||||
- `XIC_V2_CONTROL_FLOW_SUMMARY.md`
|
||||
|
||||
---
|
||||
|
||||
**XIC v2 Control Flow - Ready to Use** ✅
|
||||
Reference in New Issue
Block a user