https://github.com/legionio/lex-synapse
Cognitive routing layer for LegionIO task chains — attention, transformation, and routing with confidence scoring, pain signals, and self-governance
https://github.com/legionio/lex-synapse
Last synced: 2 months ago
JSON representation
Cognitive routing layer for LegionIO task chains — attention, transformation, and routing with confidence scoring, pain signals, and self-governance
- Host: GitHub
- URL: https://github.com/legionio/lex-synapse
- Owner: LegionIO
- License: apache-2.0
- Created: 2026-03-17T20:49:00.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T23:36:46.000Z (3 months ago)
- Last Synced: 2026-04-02T07:58:58.152Z (3 months ago)
- Language: Ruby
- Size: 211 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# lex-synapse
Cognitive routing layer for [LegionIO](https://github.com/LegionIO/LegionIO) task chains. Wraps task relationships with observation, learning, confidence scoring, pain signals, and self-governance.
## Installation
```bash
gem install lex-synapse
```
Or add to your Gemfile:
```ruby
gem 'lex-synapse'
```
## Standalone Client
Use the synapse engine without the full LegionIO framework:
```ruby
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
```
## Architecture
### Three-Layer Model
```
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
```
### Confidence Scoring
Each synapse has a confidence score (0.0-1.0) that governs what it's allowed to do:
| Range | Mode | Permitted Actions |
|-------|------|-------------------|
| 0.0-0.3 | OBSERVE | Log what it would do, pass through unchanged |
| 0.3-0.6 | FILTER | Can suppress signals, cannot modify |
| 0.6-0.8 | TRANSFORM | Can filter + transform within defined schemas |
| 0.8-1.0 | AUTONOMOUS | Can self-modify rules, infer transforms, adjust routing |
**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)
### Pain Signals
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)
### 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
## Runners
### Evaluate
`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.
### Pain
`handle_pain(synapse_id:, task_id:)`
Downstream failure handler. Records failed signal, adjusts confidence, checks for auto-revert threshold, may dampen synapse.
### Crystallize
`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
`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
`revert(synapse_id:, to_version:, trigger:)`
Rolls back to a previous mutation version, restoring the before_state.
### Report
`report(synapse_id:)`
Aggregates stats: confidence, status, 24h signal count, success rate, last mutation.
### Dream
`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
`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
`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.
## Relationship Wrapper
Wrap existing Layer 1 relationships as synapses (opt-in, zero breaking changes):
```ruby
relationship = { id: 42, trigger_function_id: 1, function_id: 2,
conditions: '{"all":[...]}', transformation: '{"template":"..."}' }
synapse = Legion::Extensions::Synapse::Helpers::RelationshipWrapper.wrap(relationship)
```
## Transport
- **Exchange**: `synapse` (inherits from `Legion::Transport::Exchanges::Task`)
- **Queues**: `synapse.evaluate`, `synapse.pain`
- **Routing keys**: `synapse.evaluate`, `task.failed`
## Autonomous Observation Mode
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.
## Adversarial Challenge Phase
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.
## Data Model
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).
## Dependencies
- `lex-conditioner` >= 0.3.0
- `lex-transformer` >= 0.3.0
- Ruby >= 3.4
- [LegionIO](https://github.com/LegionIO/LegionIO) framework (for AMQP actor mode)
- Standalone Client works without the framework (requires Sequel + database)
## License
MIT