vibe_s.py

"""
VIBE-S (Vector-Integrated Binary Extension - Semantic) Protocol
================================================================

Ultra-lightweight 24-bit protocol for machine-to-machine communication
with semantic context.

CORE-24 Bit Structure:
[MODE:1][SRC:3][TYPE:3][INTENT:3][DOMAIN:4][SEC:2][PRIORITY:3][ACTION_HINT:3][RSV:2] = 24 bits
"""

from typing import Dict, Union
from enum import IntEnum


class Mode(IntEnum):
    """MODE field (1 bit)"""
    CORE = 0
    EXTENDED = 1


class Source(IntEnum):
    """SRC field (3 bits)"""
    HUMAN = 0
    AI_MODEL = 1
    SYSTEM = 2
    SENSOR = 3
    HYBRID = 4
    EXTERNAL = 5
    UNKNOWN = 6
    RESERVED = 7


class Type(IntEnum):
    """TYPE field (3 bits)"""
    QUERY = 0
    REQUEST = 1
    INFO = 2
    ALERT = 3
    COMMAND = 4
    COMMENT = 5
    PLAN = 6
    EMOTION = 7


class Intent(IntEnum):
    """INTENT field (3 bits)"""
    LEARN = 0
    REQUEST_ACTION = 1
    COMMAND = 2
    WARN = 3
    DISCUSS = 4
    SOLVE = 5
    INFORM = 6
    CONFIRM = 7


class Domain(IntEnum):
    """DOMAIN field (4 bits)"""
    GENERAL = 0
    FINANCE = 1
    HEALTH = 2
    IOT = 3
    SOFTWARE = 4
    AI = 5
    EDUCATION = 6
    SOCIAL = 7
    LEGAL = 8
    SECURITY = 9
    LOGISTICS = 10
    ENERGY = 11
    COMMERCE = 12
    MEDIA = 13
    SCIENCE = 14
    EXTENDED = 15


class Security(IntEnum):
    """SEC field (2 bits)"""
    SAFE = 0
    SUSPICIOUS = 1
    VERIFIED = 2
    UNKNOWN = 3


class Priority(IntEnum):
    """PRIORITY field (3 bits)"""
    NONE = 0
    LOW = 1
    NORMAL = 2
    HIGH = 3
    URGENT = 4
    CRITICAL = 5
    EMERGENCY = 6
    RESERVED = 7


class ActionHint(IntEnum):
    """ACTION_HINT field (3 bits)"""
    INFO_ONLY = 0
    INTERPRETABLE = 1
    PROCESSING_REQUIRED = 2
    RESPONSE_EXPECTED = 3
    DECISION_REQUIRED = 4
    ACTION_REQUIRED = 5
    URGENT_ACTION = 6
    RESERVED = 7


# Bit positions (from MSB)
BIT_POSITIONS = {
    'MODE': 23,
    'SRC': 20,      # 3 bits: 22-20
    'TYPE': 17,     # 3 bits: 19-17
    'INTENT': 14,   # 3 bits: 16-14
    'DOMAIN': 10,   # 4 bits: 13-10
    'SEC': 8,       # 2 bits: 9-8
    'PRIORITY': 5,  # 3 bits: 7-5
    'ACTION_HINT': 2,  # 3 bits: 4-2
    'RSV': 0        # 2 bits: 1-0
}

# Bit masks
BIT_MASKS = {
    'MODE': 0x1,      # 1 bit
    'SRC': 0x7,       # 3 bits
    'TYPE': 0x7,      # 3 bits
    'INTENT': 0x7,    # 3 bits
    'DOMAIN': 0xF,    # 4 bits
    'SEC': 0x3,       # 2 bits
    'PRIORITY': 0x7,  # 3 bits
    'ACTION_HINT': 0x7,  # 3 bits
    'RSV': 0x3        # 2 bits
}


def encode_vibe_s(
    mode: Union[int, Mode],
    src: Union[int, Source],
    type_: Union[int, Type],
    intent: Union[int, Intent],
    domain: Union[int, Domain],
    sec: Union[int, Security],
    priority: Union[int, Priority],
    action_hint: Union[int, ActionHint],
    rsv: int = 0
) -> int:
    """
    Encode VIBE-S protocol header to 24-bit integer.

    Args:
        mode: Core (0) or Extended (1) mode
        src: Source type (0-7)
        type_: Message type (0-7)
        intent: Intent type (0-7)
        domain: Domain category (0-15)
        sec: Security level (0-3)
        priority: Priority level (0-7)
        action_hint: Action hint type (0-7)
        rsv: Reserved bits (default: 0)

    Returns:
        24-bit integer representation
    """
    # Validate inputs
    assert 0 <= mode <= 1, f"MODE must be 0-1, got {mode}"
    assert 0 <= src <= 7, f"SRC must be 0-7, got {src}"
    assert 0 <= type_ <= 7, f"TYPE must be 0-7, got {type_}"
    assert 0 <= intent <= 7, f"INTENT must be 0-7, got {intent}"
    assert 0 <= domain <= 15, f"DOMAIN must be 0-15, got {domain}"
    assert 0 <= sec <= 3, f"SEC must be 0-3, got {sec}"
    assert 0 <= priority <= 7, f"PRIORITY must be 0-7, got {priority}"
    assert 0 <= action_hint <= 7, f"ACTION_HINT must be 0-7, got {action_hint}"
    assert 0 <= rsv <= 3, f"RSV must be 0-3, got {rsv}"

    # Build 24-bit header
    header = 0
    header |= (int(mode) & BIT_MASKS['MODE']) << BIT_POSITIONS['MODE']
    header |= (int(src) & BIT_MASKS['SRC']) << BIT_POSITIONS['SRC']
    header |= (int(type_) & BIT_MASKS['TYPE']) << BIT_POSITIONS['TYPE']
    header |= (int(intent) & BIT_MASKS['INTENT']) << BIT_POSITIONS['INTENT']
    header |= (int(domain) & BIT_MASKS['DOMAIN']) << BIT_POSITIONS['DOMAIN']
    header |= (int(sec) & BIT_MASKS['SEC']) << BIT_POSITIONS['SEC']
    header |= (int(priority) & BIT_MASKS['PRIORITY']) << BIT_POSITIONS['PRIORITY']
    header |= (int(action_hint) & BIT_MASKS['ACTION_HINT']) << BIT_POSITIONS['ACTION_HINT']
    header |= (int(rsv) & BIT_MASKS['RSV']) << BIT_POSITIONS['RSV']

    return header & 0xFFFFFF  # Ensure 24-bit


def decode_vibe_s(header: int) -> Dict[str, Union[int, str]]:
    """
    Decode 24-bit VIBE-S header to dictionary.

    Args:
        header: 24-bit integer header

    Returns:
        Dictionary with decoded fields and their names
    """
    assert 0 <= header <= 0xFFFFFF, f"Header must be 24-bit (0-0xFFFFFF), got {header}"

    # Extract bit fields
    mode = (header >> BIT_POSITIONS['MODE']) & BIT_MASKS['MODE']
    src = (header >> BIT_POSITIONS['SRC']) & BIT_MASKS['SRC']
    type_ = (header >> BIT_POSITIONS['TYPE']) & BIT_MASKS['TYPE']
    intent = (header >> BIT_POSITIONS['INTENT']) & BIT_MASKS['INTENT']
    domain = (header >> BIT_POSITIONS['DOMAIN']) & BIT_MASKS['DOMAIN']
    sec = (header >> BIT_POSITIONS['SEC']) & BIT_MASKS['SEC']
    priority = (header >> BIT_POSITIONS['PRIORITY']) & BIT_MASKS['PRIORITY']
    action_hint = (header >> BIT_POSITIONS['ACTION_HINT']) & BIT_MASKS['ACTION_HINT']
    rsv = (header >> BIT_POSITIONS['RSV']) & BIT_MASKS['RSV']

    # Map to names
    mode_names = ['Core Mode', 'Extended Mode']
    src_names = ['Human', 'AI Model', 'System', 'Sensor', 'Hybrid', 'External', 'Unknown', 'Reserved']
    type_names = ['Query', 'Request', 'Info', 'Alert', 'Command', 'Comment', 'Plan', 'Emotion']
    intent_names = ['Learn', 'Request Action', 'Command', 'Warn', 'Discuss', 'Solve', 'Inform', 'Confirm']
    domain_names = ['General', 'Finance', 'Health', 'IoT', 'Software', 'AI', 'Education', 'Social',
                    'Legal', 'Security', 'Logistics', 'Energy', 'Commerce', 'Media', 'Science', 'Extended']
    sec_names = ['Safe', 'Suspicious', 'Verified', 'Unknown']
    priority_names = ['None', 'Low', 'Normal', 'High', 'Urgent', 'Critical', 'Emergency', 'Reserved']
    action_hint_names = ['Info Only', 'Interpretable', 'Processing Required', 'Response Expected',
                         'Decision Required', 'Action Required', 'Urgent Action', 'Reserved']

    return {
        'mode': mode,
        'mode_name': mode_names[mode],
        'src': src,
        'src_name': src_names[src],
        'type': type_,
        'type_name': type_names[type_],
        'intent': intent,
        'intent_name': intent_names[intent],
        'domain': domain,
        'domain_name': domain_names[domain],
        'sec': sec,
        'sec_name': sec_names[sec],
        'priority': priority,
        'priority_name': priority_names[priority],
        'action_hint': action_hint,
        'action_hint_name': action_hint_names[action_hint],
        'rsv': rsv,
        'header': header
    }


def to_binary_string(header: int) -> str:
    """
    Convert 24-bit header to binary string representation.

    Args:
        header: 24-bit integer header

    Returns:
        24-character binary string
    """
    assert 0 <= header <= 0xFFFFFF, f"Header must be 24-bit (0-0xFFFFFF), got {header}"
    return format(header, '024b')


def to_hex(header: int) -> str:
    """
    Convert 24-bit header to hexadecimal string.

    Args:
        header: 24-bit integer header

    Returns:
        6-character hex string (with 0x prefix)
    """
    assert 0 <= header <= 0xFFFFFF, f"Header must be 24-bit (0-0xFFFFFF), got {header}"
    return f"0x{header:06X}"


def format_header(header: int) -> str:
    """
    Format header with field boundaries for visualization.

    Args:
        header: 24-bit integer header

    Returns:
        Formatted binary string with field separators
    """
    binary = to_binary_string(header)
    # [MODE:1][SRC:3][TYPE:3][INTENT:3][DOMAIN:4][SEC:2][PRIORITY:3][ACTION_HINT:3][RSV:2]
    formatted = (
        f"[{binary[0:1]}]"           # MODE: 1 bit
        f"[{binary[1:4]}]"           # SRC: 3 bits
        f"[{binary[4:7]}]"           # TYPE: 3 bits
        f"[{binary[7:10]}]"          # INTENT: 3 bits
        f"[{binary[10:14]}]"         # DOMAIN: 4 bits
        f"[{binary[14:16]}]"         # SEC: 2 bits
        f"[{binary[16:19]}]"         # PRIORITY: 3 bits
        f"[{binary[19:22]}]"         # ACTION_HINT: 3 bits
        f"[{binary[22:24]}]"         # RSV: 2 bits
    )
    return formatted


def print_header_info(header: int, description: str = ""):
    """
    Print detailed header information.

    Args:
        header: 24-bit integer header
        description: Optional description of the header
    """
    decoded = decode_vibe_s(header)

    print(f"\n{'='*70}")
    if description:
        print(f"Description: {description}")
    print(f"{'='*70}")
    print(f"Header (int):  {header}")
    print(f"Header (hex):  {to_hex(header)}")
    print(f"Header (bin):  {to_binary_string(header)}")
    print(f"Formatted:     {format_header(header)}")
    print(f"{'-'*70}")
    print(f"MODE:        {decoded['mode']} = {decoded['mode_name']}")
    print(f"SRC:         {decoded['src']} = {decoded['src_name']}")
    print(f"TYPE:        {decoded['type']} = {decoded['type_name']}")
    print(f"INTENT:      {decoded['intent']} = {decoded['intent_name']}")
    print(f"DOMAIN:      {decoded['domain']} = {decoded['domain_name']}")
    print(f"SEC:         {decoded['sec']} = {decoded['sec_name']}")
    print(f"PRIORITY:    {decoded['priority']} = {decoded['priority_name']}")
    print(f"ACTION_HINT: {decoded['action_hint']} = {decoded['action_hint_name']}")
    print(f"RSV:         {decoded['rsv']}")
    print(f"{'='*70}\n")


if __name__ == "__main__":
    # Quick test
    print("VIBE-S Protocol Implementation")
    print("=" * 70)

    # Example: AI Model sending command to transfer funds
    header = encode_vibe_s(
        mode=Mode.CORE,
        src=Source.AI_MODEL,
        type_=Type.COMMAND,
        intent=Intent.COMMAND,
        domain=Domain.FINANCE,
        sec=Security.SAFE,
        priority=Priority.HIGH,
        action_hint=ActionHint.ACTION_REQUIRED
    )

    print_header_info(header, "AI Model - Financial Transfer Command")