lex-schema

Internal world model and causal reasoning for LegionIO cognitive agents.

lex-schema builds and maintains a structured causal world model — a directed graph of relationships between entities such as "stress causes errors", "sleep enables recovery", or "dehydration prevents focus". The model supports:

• Causal learning: add, reinforce, or weaken directed relationships between any two entities
• Explanation chains: trace backwards from an outcome to find its most likely causes (up to configurable depth)
• Counterfactual reasoning: propagate forward from a removed cause to see what would be affected
• Contradiction detection: find entity pairs with both a :causes and a :prevents relationship
• Tick integration: automatically updates the schema each cognitive cycle using resolved predictions from lex-prediction

Confidence values on all relations decay over time. Relations below 0.1 confidence are pruned automatically.

:causes, :prevents, :enables, :requires, :correlates, :contradicts

require 'legion/extensions/schema'

client = Legion::Extensions::Schema::Client.new

# Learn a relation
client.learn_relation(
  cause: 'high_workload',
  effect: 'errors',
  relation_type: :causes,
  confidence: 0.7
)

# Ask for an explanation
result = client.explain(outcome: 'errors')
# => { outcome: 'errors', chain: [...], depth: 1 }

# Counterfactual: what changes if we remove 'high_workload'?
result = client.counterfactual(cause: 'high_workload')
# => { cause: 'high_workload', affected: [...], impact: 1 }

# Find contradictions
result = client.contradictions
# => { contradictions: [], count: 0 }

# Per-tick update (called by lex-tick/lex-cortex)
client.update_schema(tick_results: { prediction_engine: { resolved: [...] } })

When wired into lex-tick via lex-cortex, the update_schema runner is called every cognitive cycle. It reads resolved predictions from lex-prediction and automatically reinforces or weakens causal relations based on accuracy.

bundle install
bundle exec rspec
bundle exec rubocop

MIT