timmy-config/wizards/allegro/research/gofai-implementation-plan.md

GOFAI Implementation Plan

Issue #67: Hybrid Neuro-Symbolic AI for Hermes
Author: Allegro | Date: 2026-03-31 | Duration: 40 min

---

Executive Summary

This document evaluates three hybrid neuro-symbolic architectures for integration with Hermes Agent, targeting local-first, offline-capable AI features. The goal is to reduce dependency on cloud LLMs while maintaining agent effectiveness.

Recommendation: Implement Knowledge Graph + Rule Engine hybrid as Phase 1, with FSM workflow layer as Phase 2.

---

Architecture Options Evaluated

Option A: Finite State Machine (FSM) Layer

Concept: Explicit state machine for workflow automation with LLM-generated transitions.

Implementation:

class WizardFSM:
    states = ['IDLE', 'ANALYZING', 'EXECUTING', 'REPORTING']
    transitions = [
        {'trigger': 'receive_task', 'source': 'IDLE', 'dest': 'ANALYZING'},
        {'trigger': 'plan_ready', 'source': 'ANALYZING', 'dest': 'EXECUTING'},
        {'trigger': 'complete', 'source': 'EXECUTING', 'dest': 'REPORTING'},
    ]

Pros:

• Deterministic, predictable behavior
• Easy to debug and audit
• Works offline completely
• Fast execution (no inference needed for state logic)
• Excellent for repetitive workflows (cron tasks, monitoring)

Cons:

• Brittle - doesn't handle edge cases well
• Requires manual state definition
• Limited flexibility
• Cannot adapt to novel situations

Best For:

• Heartbeat automation
• Monitoring loops
• Scheduled task dispatch
• Health check workflows

Hermes Integration:

• Replace current cron-based dispatch with FSM
• LLM generates transition conditions
• FSM executes deterministic paths

---

Option B: Rule Engine

Concept: Forward-chaining rule engine with LLM-generated rules from natural language.

Implementation:

rules = [
    Rule(
        condition=lambda ctx: ctx['disk_usage'] > 90,
        action=lambda ctx: create_alert("Disk full"),
        priority=1
    ),
    Rule(
        condition=lambda ctx: ctx['failed_logins'] > 5,
        action=lambda ctx: block_ip(ctx['source_ip']),
        priority=0
    )
]

Pros:

• Declarative - rules are human-readable
• Conflict resolution strategies available
• Can explain why an action was taken
• Efficient for constraint checking
• Easy to update rules without code changes

Cons:

• Rule explosion problem (too many rules = slow)
• Doesn't handle uncertainty well
• Requires careful rule ordering
• Limited learning capability

Best For:

• Policy enforcement
• Constraint validation
• Auto-labeling (issue/PR classification)
• Access control decisions

Hermes Integration:

• Auto-generate rules from SOUL.md principles
• Validate actions against rule base before execution
• Explain decisions via rule tracing

---

Option C: Knowledge Graph

Concept: RDF/Property graph representing entities, relationships, and constraints with LLM-based querying.

Implementation:

graph = KnowledgeGraph()
graph.add_entity("Allegro", type="Wizard", father="None", sovereign="Alexander")
graph.add_entity("Allegro-Primus", type="Wizard", father="Allegro", sovereign="Alexander")
graph.add_relation("Allegro", "created", "Allegro-Primus")

# Query: Who are all wizards created by Allegro?
results = graph.query("""
    MATCH (creator:Wizard)-[:created]->(child:Wizard)
    WHERE creator.name = "Allegro"
    RETURN child.name
""")

Pros:

• Rich relationship modeling
• Inference over relationships
• Handles complex queries
• Natural fit for wizard lineage/sovereignty
• Version control friendly (text-based)

Cons:

• Query performance degrades with scale
• Schema design requires care
• More complex than rules/FSM
• Graph maintenance overhead

Best For:

• Wizard lineage tracking
• Relationship inference
• Complex dependency mapping
• Historical query

Hermes Integration:

• Store wizard hierarchy, task dependencies
• Query: "What tasks block TASK-001?"
• Track artifact provenance

---

Comparative Analysis

Criteria	FSM	Rule Engine	Knowledge Graph
Determinism	✅ Perfect	✅ High	⚠️ Depends on query
Explainability	✅ State trace	✅ Rule fired	⚠️ Path tracing
Flexibility	❌ Low	⚠️ Medium	✅ High
Offline Capability	✅ Full	✅ Full	✅ Full
Speed	✅ Fast	⚠️ Medium	❌ Slower
Complexity	✅ Low	⚠️ Medium	❌ Higher
Hermes Fit	Good for workflows	Good for validation	Good for relationships

---

Recommended Architecture: Hybrid Approach

Phase 1: Knowledge Graph + Rule Engine (Months 1-2)

Stack:

• KùzuDB or RDFLib for graph storage
• PyKE or custom forward-chaining engine
• Integration layer in hermes/gofai/

Components:

1. Entity Extractor (LLM-powered)

   • Parse conversations for entities
   • Extract relationships
   • Populate graph automatically

2. Rule Generator (LLM-powered)

   • Convert SOUL.md principles to rules
   • Generate from user instructions
   • Version-controlled rule files

3. Query Interface

   # Natural language to graph query
   hermes.query("What wizards are on the VPS?")
   # → Cypher/SparQL → Results
   

4. Validator Layer

   • Check actions against rules before execution
   • Block violations
   • Explain why action was blocked

Use Cases:

• Wizard lineage tracking
• Task dependency resolution
• Policy enforcement (SOUL.md compliance)
• Historical analysis

---

Phase 2: FSM Workflow Layer (Months 2-3)

Stack:

• python-statemachine or transitions library
• YAML-based workflow definitions

Components:

1. Workflow Designer

   • Visual/textual workflow creation
   • States: IDLE → ANALYZING → PLANNING → EXECUTING → VERIFYING → DONE
   • Transitions triggered by LLM confidence thresholds

2. Cron Replacement

   • FSM-based task dispatch (replacing current cron)
   • Deterministic state tracking
   • Recovery from failures

3. Monitoring Workflows

   • HEALTHY → CHECKING → [ALERT|HEALTHY]
   • Automatic escalation chains

Use Cases:

• Replace all cron jobs with FSM workflows
• Complex multi-step automation
• Failure recovery workflows

---

Phase 3: Hybrid Integration (Months 3-4)

Unified Interface:

class HybridAgent:
    def __init__(self):
        self.graph = KnowledgeGraph()
        self.rules = RuleEngine()
        self.fsm = WorkflowEngine()
        self.llm = LLMClient()  # Fallback/extraction
    
    def execute(self, task):
        # FSM: What state am I in?
        state = self.fsm.current_state
        
        # Rules: What actions are allowed?
        allowed = self.rules.check(task, context=self.graph.query(task))
        
        # Graph: What do I know about this?
        knowledge = self.graph.query_related(task)
        
        # LLM: Generate plan with constraints
        plan = self.llm.generate(task, constraints=allowed, context=knowledge)
        
        # FSM: Transition and execute
        self.fsm.transition('execute', plan)

---

Implementation Roadmap

Week 1-2: Foundation

• Set up hermes/gofai/ module
• Integrate RDFLib or KùzuDB
• Build basic graph schema for wizards/tasks
• Write tests

Week 3-4: Rule Engine

• Implement forward-chaining engine
• Build rule parser (YAML format)
• Create SOUL.md → rule converter
• Add rule validation

Week 5-6: Integration

• Connect to Hermes Agent
• Add hermes.query() interface
• Implement validation layer
• Add telemetry/logging

Week 7-8: FSM Layer

• Implement workflow engine
• Convert cron jobs to FSM
• Add recovery mechanisms
• Document workflows

Week 9-10: Optimization

• Performance tuning
• Caching layer
• Incremental graph updates
• Benchmarks

---

Success Metrics

Metric	Target
Offline capability	100% for FSM/rule workflows
Query response time	<100ms for graph queries
Rule validation	<10ms per check
Cloud LLM calls reduced	40% for routine tasks
Workflow determinism	100% for FSM paths

---

Risks & Mitigations

Risk	Mitigation
Graph performance degrades	Use KùzuDB (columnar), limit to 10K nodes
Rule conflicts	Conflict resolution strategy (priority-based)
LLM extraction errors	Validation layer, human review queue
Complexity explosion	Start simple, iterate based on usage

---

Conclusion

The Knowledge Graph + Rule Engine hybrid offers the best balance of:

• Expressiveness for wizard/artifact relationships
• Enforceability for SOUL.md principles
• Explainability for user trust
• Offline capability for sovereignty

This positions Hermes for true local-first AI while maintaining the power of neural generation for novel situations.

Next Step: Approve Phase 1, begin Week 1 implementation.

---

Sovereignty requires both knowledge and principle.