scl-lang 0.1.0__py3-none-any.whl

scl/__init__.py

@@ -0,0 +1,26 @@
+"""
+SCL — Semantic Compression Language.
+
+Grammar: @anchor → verb [key: value, key: value]
+
+    >>> from scl import SCLRecord, Anchor, Relation, Scope
+    >>> from scl.parser import parse_document
+    >>> from scl.delta import Delta, SemanticState, DeltaStream
+    >>> from scl.gossip import Peer, HierarchicalSwarm
+
+Modules:
+    types       — Anchor, Relation, Scope, SCLRecord, SCLDocument
+    parser      — text → SCL AST
+    emitter     — SCL AST → text
+    grammar     — formal BNF specification
+    delta       — CRDT-style semantic state deltas
+    gossip      — hierarchical gossip protocol (100K+ agents)
+    eval        — executable SCL rules engine
+    iblt        — Invertible Bloom Lookup Tables for O(d) sync
+    braille     — compact braille encoding layer
+"""
+
+from .types import Anchor, Relation, Scope, SCLRecord, SCLDocument
+
+__version__ = "0.1.0"
+__all__ = ["Anchor", "Relation", "Scope", "SCLRecord", "SCLDocument"]

scl/braille/__init__.py

@@ -0,0 +1,14 @@
+"""
+Braille — compact encoding layer for SCL.
+
+Uses the 256 Unicode Braille characters (U+2800–U+28FF) as a bijective
+byte-to-character encoding. Each byte maps to exactly one Braille character.
+
+Modules:
+    codec       — encode/decode bytes ↔ Braille Unicode
+    fingerprint — SCLRecord → fixed-width Braille hash
+"""
+
+from .codec import encode, decode, encode_hex, encode_int
+
+__all__ = ["encode", "decode", "encode_hex", "encode_int"]

scl/braille/codec.py

@@ -0,0 +1,162 @@
+"""
+Braille Codec — encode/decode arbitrary bytes as Braille Unicode.
+
+The 256 Unicode Braille characters (U+2800 to U+28FF) map 1:1 to byte values
+0x00–0xFF. Each character's Unicode codepoint offset from U+2800 IS the byte
+value. This gives us a natural, lossless, bijective encoding.
+
+Properties:
+  - Bijective:     every byte sequence has exactly one Braille representation
+  - Lossless:      decode(encode(x)) == x for all x
+  - Fixed density:  1 byte = 1 Braille character = 3 UTF-8 bytes
+
+Token efficiency:
+  Most LLM tokenizers treat Braille characters as single tokens or small
+  multi-byte sequences, making this encoding competitive with or better than
+  hex/base64 for transmitting binary data through language models.
+
+Visual examples:
+  0x00 → ⠀ (blank)    0x01 → ⠁    0x41 ('A') → ⡁    0xFF → ⣿ (all dots)
+"""
+
+# The base codepoint for Braille patterns
+_BRAILLE_BASE = 0x2800
+
+# Pre-compute lookup tables for speed
+_BYTE_TO_BRAILLE: list[str] = [chr(_BRAILLE_BASE + i) for i in range(256)]
+_BRAILLE_TO_BYTE: dict[str, int] = {chr(_BRAILLE_BASE + i): i for i in range(256)}
+
+
+def encode(data: bytes) -> str:
+    """Encode arbitrary bytes as a Braille Unicode string.
+
+    Args:
+        data: Arbitrary byte sequence.
+
+    Returns:
+        String of Braille characters, one per input byte.
+
+    Examples:
+        >>> encode(b'\\x00')
+        '⠀'
+        >>> encode(b'\\xff')
+        '⣿'
+        >>> encode(b'hello')
+        '⡨⡥⡬⡬⡯'
+    """
+    return "".join(_BYTE_TO_BRAILLE[b] for b in data)
+
+
+def decode(braille: str) -> bytes:
+    """Decode a Braille Unicode string back to bytes.
+
+    Args:
+        braille: String of Braille characters.
+
+    Returns:
+        Original byte sequence.
+
+    Raises:
+        ValueError: If string contains non-Braille characters.
+
+    Examples:
+        >>> decode('⡨⡥⡬⡬⡯')
+        b'hello'
+    """
+    result = bytearray(len(braille))
+    for i, char in enumerate(braille):
+        cp = ord(char) - _BRAILLE_BASE
+        if cp < 0 or cp > 255:
+            raise ValueError(
+                f"Character at position {i} is not a Braille pattern: "
+                f"U+{ord(char):04X} ({char!r})"
+            )
+        result[i] = cp
+    return bytes(result)
+
+
+def encode_hex(hex_str: str) -> str:
+    """Encode a hex string as Braille.
+
+    Args:
+        hex_str: Hex string (with or without '0x' prefix, spaces allowed).
+
+    Returns:
+        Braille-encoded string.
+
+    Examples:
+        >>> encode_hex('deadbeef')
+        '⣞⣭⣾⣯'
+    """
+    hex_str = hex_str.replace(" ", "").replace("0x", "").replace("0X", "")
+    return encode(bytes.fromhex(hex_str))
+
+
+def encode_int(n: int, width: int = 4) -> str:
+    """Encode an integer as fixed-width Braille (big-endian).
+
+    Args:
+        n: Non-negative integer.
+        width: Number of bytes (= number of Braille characters).
+
+    Returns:
+        Fixed-width Braille string.
+
+    Raises:
+        ValueError: If n is negative or doesn't fit in width bytes.
+
+    Examples:
+        >>> encode_int(0, width=2)
+        '⠀⠀'
+        >>> encode_int(255, width=1)
+        '⣿'
+        >>> encode_int(65535, width=2)
+        '⣿⣿'
+    """
+    if n < 0:
+        raise ValueError(f"Cannot encode negative integer: {n}")
+    max_val = (1 << (width * 8)) - 1
+    if n > max_val:
+        raise ValueError(
+            f"Integer {n} does not fit in {width} bytes (max {max_val})"
+        )
+    return encode(n.to_bytes(width, byteorder="big"))
+
+
+def decode_int(braille: str) -> int:
+    """Decode a Braille string back to an integer (big-endian).
+
+    Args:
+        braille: Braille-encoded integer.
+
+    Returns:
+        The decoded integer.
+    """
+    return int.from_bytes(decode(braille), byteorder="big")
+
+
+def is_braille(char: str) -> bool:
+    """Check if a character is a Braille pattern (U+2800–U+28FF)."""
+    cp = ord(char)
+    return _BRAILLE_BASE <= cp <= _BRAILLE_BASE + 255
+
+
+def braille_len(braille: str) -> int:
+    """Return the number of bytes encoded in a Braille string.
+
+    Same as len(braille) since the encoding is 1:1, but explicit
+    about the semantic meaning.
+    """
+    return len(braille)
+
+
+def to_hex(braille: str) -> str:
+    """Convert Braille string to hex representation.
+
+    Useful for debugging and display.
+
+    Examples:
+        >>> to_hex('⣞⣭⣾⣯')
+        'deadbeef'
+    """
+    return decode(braille).hex()

scl/braille/fingerprint.py

@@ -0,0 +1,146 @@
+"""
+Braille Fingerprints — SCLRecord → fixed-width Braille hash.
+
+Maps SCL records and documents to compact, fixed-width Braille strings
+using SHA-256 hashing. These fingerprints serve as:
+
+  1. **Dedup keys** — identical records produce identical fingerprints
+  2. **LSH approximation** — similar records often share prefix bits
+  3. **Gossip payloads** — 4-char fingerprint = 32 bits, cheap to propagate
+  4. **Convergence checks** — Hamming distance between fingerprints estimates
+     semantic divergence between agents
+
+At scale (N → ∞):
+  - Agents broadcast fingerprints instead of full state
+  - Cluster-heads aggregate fingerprints for sub-swarms
+  - Hamming distance < ε ⟹ agents are in agreement
+  - Hamming distance > threshold ⟹ trigger challenger verification
+"""
+
+import hashlib
+
+from .codec import encode
+from ..types import SCLRecord, SCLDocument
+
+
+def fingerprint(record: SCLRecord, width: int = 4) -> str:
+    """SCL record → fixed-width Braille fingerprint.
+
+    Process:
+      1. Serialize record to canonical bytes (record.to_bytes())
+      2. SHA-256 hash
+      3. Take first `width` bytes of hash
+      4. Encode as Braille
+
+    Args:
+        record: The SCL record to fingerprint.
+        width: Number of Braille characters (= bytes of hash). Default 4 (32 bits).
+
+    Returns:
+        String of `width` Braille characters.
+
+    Examples:
+        >>> from src.scl.types import Anchor, Relation, Scope, SCLRecord
+        >>> r = SCLRecord(Anchor('router'), Relation('select'), Scope({'model': 'qwen3:4b'}))
+        >>> len(fingerprint(r))
+        4
+        >>> fingerprint(r) == fingerprint(r)  # deterministic
+        True
+    """
+    h = hashlib.sha256(record.to_bytes()).digest()
+    return encode(h[:width])
+
+
+def fingerprint_document(doc: SCLDocument, width: int = 8) -> str:
+    """Full SCL document → single Braille fingerprint.
+
+    Hashes the concatenated binary of all records.
+
+    Args:
+        doc: The SCL document to fingerprint.
+        width: Number of Braille characters. Default 8 (64 bits).
+
+    Returns:
+        String of `width` Braille characters.
+    """
+    h = hashlib.sha256(doc.to_bytes()).digest()
+    return encode(h[:width])
+
+
+def fingerprint_batch(records: list[SCLRecord], width: int = 8) -> str:
+    """Multiple SCL records → single Braille fingerprint.
+
+    Convenience wrapper: creates a temporary document and fingerprints it.
+    """
+    doc = SCLDocument(records=records)
+    return fingerprint_document(doc, width=width)
+
+
+def fingerprint_match(fp1: str, fp2: str) -> bool:
+    """Compare two fingerprints for exact equality."""
+    return fp1 == fp2
+
+
+def similarity(fp1: str, fp2: str) -> float:
+    """Hamming-distance-based similarity between two fingerprints.
+
+    Compares bit-by-bit. Returns 0.0 (completely different) to 1.0 (identical).
+
+    At scale, this is the convergence metric:
+      - similarity > 0.9 → agents agree, no action needed
+      - similarity 0.5–0.9 → partial agreement, may need verification
+      - similarity < 0.5 → disagreement, trigger challenger/swarm
+
+    Args:
+        fp1: First Braille fingerprint.
+        fp2: Second Braille fingerprint.
+
+    Returns:
+        Float in [0.0, 1.0].
+
+    Raises:
+        ValueError: If fingerprints have different lengths.
+    """
+    if len(fp1) != len(fp2):
+        raise ValueError(
+            f"Fingerprints must have same length: {len(fp1)} vs {len(fp2)}"
+        )
+
+    if not fp1:
+        return 1.0
+
+    total_bits = len(fp1) * 8
+    matching_bits = 0
+
+    for c1, c2 in zip(fp1, fp2):
+        b1 = ord(c1) - 0x2800
+        b2 = ord(c2) - 0x2800
+        # XOR gives bits that differ; popcount gives number of differing bits
+        xor = b1 ^ b2
+        differing = bin(xor).count("1")
+        matching_bits += 8 - differing
+
+    return matching_bits / total_bits
+
+
+def hamming_distance(fp1: str, fp2: str) -> int:
+    """Raw Hamming distance in bits between two fingerprints.
+
+    Args:
+        fp1: First Braille fingerprint.
+        fp2: Second Braille fingerprint.
+
+    Returns:
+        Number of differing bits.
+    """
+    if len(fp1) != len(fp2):
+        raise ValueError(
+            f"Fingerprints must have same length: {len(fp1)} vs {len(fp2)}"
+        )
+
+    distance = 0
+    for c1, c2 in zip(fp1, fp2):
+        b1 = ord(c1) - 0x2800
+        b2 = ord(c2) - 0x2800
+        distance += bin(b1 ^ b2).count("1")
+    return distance