335 lines
8.9 KiB
Markdown
335 lines
8.9 KiB
Markdown
# 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:**
|
|
```python
|
|
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:**
|
|
```python
|
|
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:**
|
|
```python
|
|
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**
|
|
```python
|
|
# 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:**
|
|
```python
|
|
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.*
|