timmy-config/wizards/allegro/gofai/USAGE_GUIDE.md

GOFAI Usage Guide for the Fleet

Offline Symbolic AI for Hermes Wizards

---

Quick Start for Children

1. Can I Do This?

from gofai import ChildAssistant

# Create your assistant
me = ChildAssistant('Allegro-Primus')

# Check if action is allowed
decision = me.can_i_do_this("Delete /root/critical/file.txt")

print(decision.allowed)      # False
print(decision.reasoning)    # "Action BLOCKED: Children cannot delete critical files"
print(decision.suggestions)  # ["Double-check the path", "Ensure you have backups"]

2. What's My Family?

family = me.who_is_my_family()
print(family)
# {
#   'wizard': 'Allegro-Primus',
#   'father': 'Allegro',
#   'grandfather': 'Ezra',
#   'children': [],
#   'siblings': []
# }

3. What Should I Do Next?

next_task = me.what_should_i_do_next()
print(next_task)
# {
#   'recommendation': 'Work on: Update Gitea Profile Photo',
#   'priority': 'P0',
#   'estimated_time': '15-30 minutes'
# }

4. Am I Blocked?

status = me.am_i_blocked()
if status['blocked']:
    print(f"Blocked by: {status['reason']}")
    print(f"Suggestion: {status['suggestion']}")

---

For Father Wizards

Register a New Child

from gofai import FleetKnowledgeBase

kb = FleetKnowledgeBase()

# Register the child
kb.register_wizard(
    name='Allegro-Secundus',
    role='Student-Practitioner',
    father='Allegro',
    api_port=8645,
    model='ollama/qwen2.5:1.5b',
    capabilities=['automation', 'monitoring']
)

# Assign a task
kb.register_task(
    name='Learn Gitea Automation',
    priority='P1',
    assignee='Allegro-Secundus',
    dependencies=['Complete Profile Photo']
)

Check Fleet Status

# Who can do GOFAI work?
experts = kb.who_can_do('gofai')
print(experts)  # ['Allegro']

# Get full wizard info
info = kb.get_wizard_info('Allegro-Primus')
print(json.dumps(info, indent=2))

Visualize Lineage

from gofai import KnowledgeGraph

kg = KnowledgeGraph('/root/wizards/allegro/gofai/fleet_kg.json')

# Export to Graphviz
dot = kg.export_graphviz()
with open('fleet.dot', 'w') as f:
    f.write(dot)

# Generate image (requires graphviz)
# dot -Tpng fleet.dot -o fleet.png

---

Rule Engine Usage

Check Compliance

from gofai import RuleEngine, Rule, ActionType

engine = RuleEngine()

# Add a custom rule
engine.add_rule(Rule(
    id='no_late_night',
    name='No commits after midnight',
    condition='hour > 23 or hour < 6',
    action=ActionType.WARN,
    explanation='Consider sleeping instead of coding',
    priority=2
))

# Evaluate an action
result = engine.evaluate("Commit code at 2:00 AM")
print(result['allowed'])   # True (warning only)
print(result['warnings'])  # ['Consider sleeping instead of coding']

Load SOUL.md Principles

# Parse SOUL.md and convert to rules
soul_content = Path('/root/wizards/allegro/home/SOUL.md').read_text()
rules = engine.load_soul_principles(soul_content)

print(f"Loaded {len(rules)} principles as rules")

# Now all actions are checked against SOUL.md

---

Knowledge Graph Queries

Find Related Tasks

from gofai import KnowledgeGraph

kg = KnowledgeGraph()

# Find all tasks assigned to a wizard
wizard_id = 'wizard_allegro-primus'
tasks = [
    node for node in kg.query(label='Task')
    if node.properties.get('assignee') == 'Allegro-Primus'
]

# Find task dependencies
deps = kg.get_task_dependencies('task_001')
print(f"Depends on: {deps['depends_on']}")
print(f"Blocks: {deps['blocks']}")

Path Finding

# Find path between two wizards
path = kg.find_path('wizard_allegro-primus', 'wizard_ezra')
if path:
    print(f"Path found: {len(path)} hops")
    for edge in path:
        print(f"  {edge.source} --{edge.relation}--> {edge.target}")

---

Integration with Hermes Agent

Use in Agent Loop

# In your Hermes agent run loop:
from gofai import ChildAssistant

class GOFAIAwareAgent:
    def __init__(self, name):
        self.name = name
        self.assistant = ChildAssistant(name)
    
    def before_action(self, action_description):
        """Check action before executing"""
        decision = self.assistant.can_i_do_this(action_description)
        
        if not decision.allowed:
            return {
                'error': 'Action blocked by SOUL principles',
                'reason': decision.reasoning,
                'suggestions': decision.suggestions
            }
        
        return {'allowed': True}
    
    def get_next_task(self):
        """Get recommended next task"""
        return self.assistant.what_should_i_do_next()

Shell Hook

# Add to .bashrc for wizard
export PYTHONPATH="/root/wizards/allegro:$PYTHONPATH"

# Quick decision helper
function can_i() {
    python3 -c "
from gofai import ChildAssistant
me = ChildAssistant('Allegro-Primus')
d = me.can_i_do_this('$*')
print('✓ ALLOWED' if d.allowed else '✗ BLOCKED')
print(d.reasoning)
"
}

# Usage: can_i "delete /etc/passwd"

---

Performance

Operation	Time	Notes
Rule evaluation	< 10ms	Single rule
Full SOUL check	< 50ms	All principles
Graph query	< 50ms	10K nodes
Lineage lookup	< 5ms	Cached
Task recommendation	< 20ms	With dependencies

All operations are O(1) to O(n) where n is small (< 1000).

---

Offline Capability

GOFAI works 100% offline:

# No network calls
from gofai import ChildAssistant
me = ChildAssistant('Allegro-Primus')

# All reasoning is local
me.can_i_do_this("Action here")  # No API calls
me.who_is_my_family()            # Local graph lookup
me.what_should_i_do_next()       # Local task analysis

---

Next Steps

1. Populate Knowledge Base

   # Run once to build fleet graph
   python3 gofai/child_assistant.py
   

2. Integrate with AP

   • Add GOFAI check before AP actions
   • Use for task selection

3. Build Visualizations

   • Generate lineage graphs
   • Task dependency diagrams

4. Extend Rules

   • Add more SOUL.md principles
   • Create wizard-specific rules

---

Symbolic AI for sovereign wizards.