clm-kernel 0.0.0__py3-none-any.whl

clm/layer3/satori/speech_act.py

@@ -0,0 +1,279 @@
+"""Layer 3 Satori Speech-Act Transducer & Models (DEL-390-02, INV-390-01).
+
+Implements Searle-Austin speech act taxonomy:
+- Assertive: statements of fact, belief, or state verification
+- Directive: instructions, queries, and requests for action
+- Commissive: commitments, promises, and contracts
+- Expressive: psychological states, greetings, acknowledgments
+- Declarative: ontological declarations, approvals, and mutations
+
+Also implements Satori binary AST encoding/decoding matching TypeScript & Rust.
+"""
+from __future__ import annotations
+
+import json
+import struct
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Tuple
+
+SATORI_OPCODES = {
+    "text": 0x01,
+    "at": 0x02,
+    "quote": 0x03,
+    "image": 0x04,
+    "audio": 0x05,
+    "video": 0x06,
+    "button": 0x07,
+    "action": 0x08,
+    "card": 0x09,
+    "execute": 0x0A,
+    "witness": 0x0B,
+    "custom": 0x0C,
+    "message": 0x10,
+}
+
+OPCODES_TO_TYPE = {v: k for k, v in SATORI_OPCODES.items()}
+
+
+class SpeechActType(str, Enum):
+    """Searle-Austin illocutionary taxonomy."""
+    ASSERTIVE = "assertive"
+    DIRECTIVE = "directive"
+    COMMISSIVE = "commissive"
+    EXPRESSIVE = "expressive"
+    DECLARATIVE = "declarative"
+
+
+@dataclass
+class SpeechAct:
+    """Conversational Speech Act container."""
+    act_type: str
+    content: str
+    user_did: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: float = field(default_factory=time.time)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    elements: List[Dict[str, Any]] = field(default_factory=list)
+
+    def to_message_node(self) -> Dict[str, Any]:
+        """Convert speech act into a Satori message AST node."""
+        els = list(self.elements)
+        if not els:
+            els = [{"type": "text", "text": self.content}]
+        node = {
+            "type": "message",
+            "id": self.id,
+            "user_did": self.user_did,
+            "speech_act_type": self.act_type,
+            "timestamp": self.timestamp,
+            "elements": els,
+        }
+        if self.metadata:
+            node["metadata"] = self.metadata
+        return node
+
+
+def encode_satori_binary(node: Dict[str, Any]) -> bytes:
+    """Encodes a Satori AST node into compact binary frame:
+    [1B opcode][2B attrLen BE][attrBytes][2B childCount BE][children...]
+    """
+    is_message = "elements" in node or node.get("type") == "message"
+    opcode = SATORI_OPCODES["message"] if is_message else SATORI_OPCODES.get(node.get("type", "custom"), 0x0C)
+
+    if is_message:
+        attrs = {
+            "id": node.get("id", ""),
+            "channel_id": node.get("channel_id", ""),
+            "user_did": node.get("user_did", ""),
+            "timestamp": node.get("timestamp", 0),
+        }
+        if "speech_act_type" in node:
+            attrs["speech_act_type"] = node["speech_act_type"]
+        children = node.get("elements", [])
+    else:
+        attrs = {k: v for k, v in node.items() if k not in ("type", "children")}
+        children = node.get("children", [])
+
+    attr_bytes = json.dumps(attrs, separators=(',', ':')).encode("utf-8")
+    encoded_children = [encode_satori_binary(c) for c in children]
+
+    buf = bytearray()
+    buf.append(opcode)
+    buf.extend(struct.pack(">H", len(attr_bytes)))
+    buf.extend(attr_bytes)
+    buf.extend(struct.pack(">H", len(children)))
+    for c_bytes in encoded_children:
+        buf.extend(c_bytes)
+
+    return bytes(buf)
+
+
+def _decode_satori_binary_with_length(buf: bytes, start_offset: int = 0) -> Tuple[Dict[str, Any], int]:
+    offset = start_offset
+    if len(buf) - offset < 5:
+        raise ValueError("Satori binary frame too short")
+
+    opcode = buf[offset]
+    offset += 1
+
+    attr_len = struct.unpack(">H", buf[offset : offset + 2])[0]
+    offset += 2
+
+    attr_bytes = buf[offset : offset + attr_len]
+    offset += attr_len
+    attrs = json.loads(attr_bytes.decode("utf-8"))
+
+    child_count = struct.unpack(">H", buf[offset : offset + 2])[0]
+    offset += 2
+
+    children = []
+    for _ in range(child_count):
+        child_node, child_bytes_read = _decode_satori_binary_with_length(buf, offset)
+        children.append(child_node)
+        offset += child_bytes_read
+
+    total_bytes_read = offset - start_offset
+
+    if opcode == SATORI_OPCODES["message"]:
+        attrs["elements"] = children
+        return attrs, total_bytes_read
+
+    node_type = OPCODES_TO_TYPE.get(opcode, "custom")
+    out = {"type": node_type}
+    out.update(attrs)
+    if children:
+        out["children"] = children
+    return out, total_bytes_read
+
+
+def decode_satori_binary(buf: bytes) -> Dict[str, Any]:
+    """Decodes binary frame back into Satori AST dictionary."""
+    node, _ = _decode_satori_binary_with_length(buf, 0)
+    return node
+
+
+def classify_speech_act(node: Dict[str, Any]) -> str:
+    """Classifies a Satori AST node into a Searle-Austin speech act category:
+    assertive, directive, commissive, expressive, or declarative.
+    """
+    if "speech_act_type" in node:
+        val = str(node["speech_act_type"]).lower()
+        if val in ("assertive", "directive", "commissive", "expressive", "declarative"):
+            return val
+        if val == "declaration":
+            return "declarative"
+
+    node_type = node.get("type", "")
+    if node_type in ("action", "execute"):
+        return "directive"
+    if node_type == "witness":
+        return "declarative"
+
+    def _extract_text(n: Dict[str, Any]) -> str:
+        res = []
+        if "text" in n:
+            res.append(str(n["text"]))
+        for child in n.get("elements", n.get("children", [])):
+            res.append(_extract_text(child))
+        return " ".join(res)
+
+    text = _extract_text(node).lower()
+    if "?" in text or text.startswith("run ") or text.startswith("can you") or text.startswith("show "):
+        return "directive"
+    if "i will" in text or "promise" in text or "commit" in text:
+        return "commissive"
+    if any(w in text for w in ("hello", "thanks", "great", "morning")):
+        return "expressive"
+    if any(w in text for w in ("declare", "approve", "hereby")):
+        return "declarative"
+    return "assertive"
+
+
+def create_assert(text: str, user_did: str, id: str = "msg-assert", **kwargs: Any) -> Dict[str, Any]:
+    """Create an assertive speech-act message AST node."""
+    return {
+        "type": "message",
+        "id": id,
+        "user_did": user_did,
+        "speech_act_type": "assertive",
+        "elements": [{"type": "text", "text": text}],
+        **kwargs,
+    }
+
+
+def create_directive(text: str, user_did: str, id: str = "msg-directive", **kwargs: Any) -> Dict[str, Any]:
+    """Create a directive speech-act message AST node."""
+    return {
+        "type": "message",
+        "id": id,
+        "user_did": user_did,
+        "speech_act_type": "directive",
+        "elements": [{"type": "text", "text": text}],
+        **kwargs,
+    }
+
+
+create_request = create_directive
+
+
+def create_commissive(text: str, user_did: str, id: str = "msg-commissive", **kwargs: Any) -> Dict[str, Any]:
+    """Create a commissive speech-act message AST node."""
+    return {
+        "type": "message",
+        "id": id,
+        "user_did": user_did,
+        "speech_act_type": "commissive",
+        "elements": [{"type": "text", "text": text}],
+        **kwargs,
+    }
+
+
+create_commit = create_commissive
+
+
+def create_expressive(text: str, user_did: str, id: str = "msg-expressive", **kwargs: Any) -> Dict[str, Any]:
+    """Create an expressive speech-act message AST node."""
+    return {
+        "type": "message",
+        "id": id,
+        "user_did": user_did,
+        "speech_act_type": "expressive",
+        "elements": [{"type": "text", "text": text}],
+        **kwargs,
+    }
+
+
+def create_declarative(text: str, user_did: str, id: str = "msg-declarative", **kwargs: Any) -> Dict[str, Any]:
+    """Create a declarative speech-act message AST node."""
+    return {
+        "type": "message",
+        "id": id,
+        "user_did": user_did,
+        "speech_act_type": "declarative",
+        "elements": [{"type": "text", "text": text}],
+        **kwargs,
+    }
+
+
+create_declare = create_declarative
+
+__all__ = [
+    "SATORI_OPCODES",
+    "OPCODES_TO_TYPE",
+    "SpeechActType",
+    "SpeechAct",
+    "encode_satori_binary",
+    "decode_satori_binary",
+    "classify_speech_act",
+    "create_assert",
+    "create_directive",
+    "create_request",
+    "create_commissive",
+    "create_commit",
+    "create_expressive",
+    "create_declarative",
+    "create_declare",
+]

clm/layer4/README.md

@@ -0,0 +1,9 @@
+# Layer 4 — Human Interaction Surface (Python Track — Generative Hypermedia CLI)
+
+Python-track L4 components: CLI REPL viewers (text-mode Generative Hypermedia surface), human refinement CLI tools, EOA sponsor signing CLI, Data Harness query tools, Process Harness discovery via `clmEval`, non-browser surfaces.
+
+Depends on: L0 (Kenotic Core), L1 (CPN VM), L2 (Storage), L3 (Network).
+
+**Generative Hypermedia Shell (CLI Track)**: Provides terminal REPL interfaces as the text-mode **Generative Hypermedia Surface** — the LLM-powered generative loop where human users provide refinement advice, navigate asset handles, execute Baldwin refactoring operations, and manage DID-bound VCard witness signatures. The CLI queries the **Data Harness** (MCard collection, Column Space $S_T$) for grounding facts and discovers available controls from the **Process Harness** (PCard/VCard graph) via `clmEval`. The **VCard Sandwich** enforces hallucination prevention at the CLI boundary.
+
+**Normative spec**: `docs/spec/30-interfaces/layer4-human-interaction-surface.md`

clm/layer4/__init__.py

@@ -0,0 +1,67 @@
+"""Layer 4 — Human Interaction Surface (Python track).
+
+Conversational gateways, visualizers, EOA sponsor signing surfaces,
+human-in-the-loop approval gates, presentation membranes, card navigation.
+
+Depends on: L0 (Kenotic Core), L1 (CPN VM), L2 (Storage), L3 (Network).
+L0–L3 MUST NOT import from this package (linear dependency rule).
+"""
+
+from clm.layer4.eoa_sponsor import (
+    derive_did,
+    derive_did_from_pubkey,
+    generate_in_memory_keypair,
+    sign_intent,
+    sign_intent_with_key,
+    verify_signature,
+)
+from clm.layer4.events import EventLog, EventType, ExecutionEvent, GatewayEvent
+from clm.layer4.gateway import CLMGateway, GatewayRouter
+from clm.layer4.membrane import (
+    ActionResult,
+    CollectionManager,
+    CollectionStats,
+    MCardBridge,
+    MCardStorage,
+    MembraneAction,
+    MembraneEvent,
+    MembraneSession,
+    PresentationMembrane,
+    RetrievalResult,
+    StorageResult,
+    VCardReceiptGenerator,
+    WebStudioMembrane,
+)
+from clm.layer4.navigation import CardGraph, CardNode, NavigationDirection
+
+__all__ = [
+    "ActionResult",
+    "CardGraph",
+    "CardNode",
+    "CLMGateway",
+    "CollectionManager",
+    "CollectionStats",
+    "EventLog",
+    "EventType",
+    "ExecutionEvent",
+    "GatewayEvent",
+    "GatewayRouter",
+    "MCardBridge",
+    "MCardStorage",
+    "MembraneAction",
+    "MembraneEvent",
+    "MembraneSession",
+    "NavigationDirection",
+    "PresentationMembrane",
+    "RetrievalResult",
+    "StorageResult",
+    "VCardReceiptGenerator",
+    "WebStudioMembrane",
+    "derive_did",
+    "derive_did_from_pubkey",
+    "generate_in_memory_keypair",
+    "sign_intent",
+    "sign_intent_with_key",
+    "verify_signature",
+]
+