Metadata-Version: 2.5
Name: scl-lang
Version: 0.1.0
Summary: Semantic Compression Language — a protocol for multi-agent state synchronization
Project-URL: Homepage, https://github.com/elevate-foundry/cortex
Project-URL: Repository, https://github.com/elevate-foundry/cortex
Author: Elevate Foundry
License-Expression: MIT
Keywords: braille-encoding,crdt,gossip-protocol,multi-agent,semantic-compression,state-synchronization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# SCL — Semantic Compression Language

A protocol for multi-agent state synchronization. Agents communicate via compressed semantic records, synchronize state through hierarchical gossip, and encode everything in braille for compact wire format.

```
@router → select [model: qwen3:4b, confidence: 0.82]
@agent_0 → mutate [task: classify, result: code]
@consensus → agree [cluster: 0, weight: 7.5]
```

## Install

```bash
pip install scl
```

## Quick Start

### Parse & Emit SCL

```python
from scl.parser import parse_record
from scl.emitter import emit_record

result = parse_record('@router → select [model: qwen3:4b, confidence: 0.82]')
record = result.record
print(record.anchor.name)     # "router"
print(record.relation.verb)   # "select"
print(record.scope.entries)   # {"model": "qwen3:4b", "confidence": "0.82"}

print(emit_record(record))
# @router → select [model: qwen3:4b, confidence: 0.82]
```

### Multi-Agent Gossip (100K+ agents)

```python
from scl.gossip import HierarchicalSwarm

swarm = HierarchicalSwarm()
swarm.add_agents_bulk([(f'agent_{i}', None, 1.0) for i in range(100_000)])

# Agent 0 discovers a fact
swarm.get_peer('agent_0').mutate({'task': 'classify', 'result': 'code'})

# Epidemic gossip — all 100K agents converge
rounds = swarm.run_until_converged()
# 2 rounds, < 1 second
```

### Semantic State Deltas (CRDTs)

```python
from scl.delta import SemanticState, DeltaStream

stream = DeltaStream()
state = SemanticState(entries={'model': 'qwen3:4b'})

# Mutations produce deltas, not full snapshots
delta = stream.append_mutation(
    agent_id='agent_0',
    changes={'confidence': '0.82'},
)

# Time travel
old_state = stream.state_at(seq=1)
stream.rollback(to_seq=1)
```

### Braille Encoding

```python
from scl.braille import encode, decode

# Bijective: 1 byte = 1 braille character (U+2800-U+28FF)
encoded = encode(b'hello')  # '⠓⠑⠇⠇⠕'
assert decode(encoded) == b'hello'
```

### Executable Rules

```python
from scl.eval import Rule, RuleEngine, Condition, Action

engine = RuleEngine()
engine.add_rule(Rule(
    name='escalate_hard',
    condition=Condition(field='complexity', op='>', value='0.8'),
    action=Action(verb='escalate', params={'to': 'swarm'}),
))

result = engine.evaluate({'complexity': '0.9'})
# Fires the escalate_hard rule
```

## Architecture

```
@anchor → verb [key: value]
   |         |       |
   |         |       +-- Scope: bounded context (dict)
   |         +---------- Relation: verb/transition
   +-------------------- Anchor: entity/subject

Records compose into Documents.
Documents synchronize via Delta Streams.
Deltas propagate via Gossip Protocol.
Wire format: Braille (1 byte = 1 char).
```

### Gossip Protocol

Two-tier hierarchical gossip with copy-on-write stamping:

1. **Intra-cluster**: Head absorbs divergent members via dict merge
2. **Inter-cluster**: All heads merge in a single pass
3. **COW broadcast**: Members share head's state by reference

100K agents converge in 2 rounds / 0.56 seconds.

### IBLT (Invertible Bloom Lookup Table)

Available for O(d) set-difference sync over constrained networks:

```python
from scl.iblt import KVCache

a = KVCache()
a.put('key1', 'val1')

b = KVCache()
b.put('key2', 'val2')

exchanged = a.sync_with(b)  # IBLT subtraction + decode
# Both now have {key1: val1, key2: val2}
```

## Grammar (BNF)

```
record     := anchor relation scope
anchor     := '@' IDENTIFIER
relation   := '→' VERB
scope      := '[' entries ']'
entries    := entry (',' entry)*
entry      := KEY ':' VALUE
document   := record ('\n' record)*
```

## License

MIT
