lex-synapse

Cognitive routing layer for LegionIO task chains. Wraps task relationships with observation, learning, confidence scoring, pain signals, and self-governance.

gem install lex-synapse

Or add to your Gemfile:

gem 'lex-synapse'

Use the synapse engine without the full LegionIO framework:

require 'legion/extensions/synapse/client'

# Optionally inject conditioner and transformer clients
conditioner = Legion::Extensions::Conditioner::Client.new
transformer = Legion::Extensions::Transformer::Client.new

client = Legion::Extensions::Synapse::Client.new(
  conditioner_client: conditioner,
  transformer_client: transformer
)

# Create a synapse
synapse = client.create(
  source_function_id: 1,
  target_function_id: 2,
  attention: '{"all":[{"fact":"status","operator":"equal","value":"open"}]}',
  transform: '{"template":"{\"message\":\"<%= title %>\"}","engine":"erb"}'
)

# Evaluate a signal through the synapse
result = client.evaluate(synapse_id: synapse.id, payload: { status: 'open', title: 'Bug fix' })
result[:success]     # => true
result[:mode]        # => :transform (based on confidence level)
result[:result]      # => { message: "Bug fix" }

# Get synapse stats
report = client.report(synapse_id: synapse.id)
report[:confidence]  # => 0.72
report[:signals_24h] # => 1
report[:success_rate] # => 1.0

Layer 1 (Bones)  — Explicit relationships defined by users (lex-tasker)
Layer 2 (Nerves) — Synapses wrapping relationships with learning (lex-synapse)
Layer 3 (Mind)   — GAIA cognitive coordination + Apollo shared knowledge

Each synapse has a confidence score (0.0-1.0) that governs what it's allowed to do:

Starting scores: explicit=0.7, emergent=0.3, seeded=0.5

Adjustments: success +0.02, failure -0.05, validation failure -0.03, 50+ consecutive successes +0.05 bonus

Decay: Unused synapses fade at 0.998x per hour (~15% per day of inactivity)

Downstream task failures propagate backward through the chain:

• Each failure reduces confidence by 0.05
• 3+ consecutive failures trigger auto-revert to last known-good state
• Extreme failure rates trigger dampening (homeostasis)

• Spike detection: Throughput >3x baseline for 60+ seconds triggers dampening
• Drought detection: Zero throughput for 10x average interval flags for review
• Baseline tracking: Exponential moving average of signals/minute

evaluate(synapse_id:, payload:, conditioner_client:, transformer_client:)

Main signal flow: load synapse, check autonomy, run attention (conditioner), run transform (transformer), record signal, adjust confidence.

handle_pain(synapse_id:, task_id:)

Downstream failure handler. Records failed signal, adjusts confidence, checks for auto-revert threshold, may dampen synapse.

crystallize(signal_pairs:, threshold: 20)

Bottom-up emergence. Given pairs of {source_function_id, target_function_id, count}, creates new synapses for pairs exceeding the threshold.

mutate(synapse_id:, mutation_type:, changes:, trigger:)

Versioned self-modification. Records before/after state snapshots. Types: attention_adjusted, transform_adjusted, route_changed, confidence_changed. Triggers: hebbian, pain, dream, gaia, manual.

revert(synapse_id:, to_version:, trigger:)

Rolls back to a previous mutation version, restoring the before_state.

report(synapse_id:)

Aggregates stats: confidence, status, 24h signal count, success rate, last mutation.

dream(synapse_id:, limit:)

Replays historical signals in simulation mode without affecting live state. Used by the dream cycle to test routing hypothesis changes.

propose(synapse_id:, ...) / proposals(synapse_id:, status:) / review_proposal(proposal_id:, status:)

Generates proposed changes (reactive on signal evaluation, proactive on periodic analysis) for AUTONOMOUS-tier synapses. Proposals enter a status lifecycle: pending -> approved/rejected/applied/expired/auto_accepted/auto_rejected.

challenge_proposal(proposal_id:) / challenges(proposal_id:) / challenger_stats

Runs the adversarial challenge pipeline on pending proposals: conflict detection -> impact scoring -> LLM challenge (gated by impact score) -> weighted aggregation -> auto-accept/reject/await-review outcome.

Wrap existing Layer 1 relationships as synapses (opt-in, zero breaking changes):

relationship = { id: 42, trigger_function_id: 1, function_id: 2,
                 conditions: '{"all":[...]}', transformation: '{"template":"..."}' }
synapse = Legion::Extensions::Synapse::Helpers::RelationshipWrapper.wrap(relationship)

• Exchange: synapse (inherits from Legion::Transport::Exchanges::Task)
• Queues: synapse.evaluate, synapse.pain
• Routing keys: synapse.evaluate, task.failed

AUTONOMOUS-tier synapses (confidence >= 0.8) generate proposals instead of directly executing changes. Proposals are reactive (triggered on signal evaluation) or proactive (generated periodically). The lex-synapse.proposals.* settings control enabled state, LLM engine options, and thresholds.

Pending proposals are subjected to a multi-stage challenge pipeline: conflict detection among sibling proposals, impact scoring, optional LLM challenge (for high-impact proposals), weighted aggregation across verdicts, and auto-accept/reject based on configurable thresholds. The lex-synapse.challenge.* settings control gating.

Five tables: synapses (core routing definition + confidence + status), synapse_mutations (versioned change history), synapse_signals (per-signal outcome records), synapse_proposals (proposal lifecycle), synapse_challenges (per-challenge verdicts).

• lex-conditioner >= 0.3.0
• lex-transformer >= 0.3.0
• Ruby >= 3.4
• LegionIO framework (for AMQP actor mode)
• Standalone Client works without the framework (requires Sequel + database)

MIT