VIBE-S Protocol

Vector-Integrated Binary Extension - Semantic

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

Overview

VIBE-S is a compact binary protocol designed to provide semantic context in machine-to-machine communication while maintaining an extremely small footprint of just 24 bits (3 bytes).

Protocol Structure

CORE-24 Bit Layout

[MODE:1][SRC:3][TYPE:3][INTENT:3][DOMAIN:4][SEC:2][PRIORITY:3][ACTION_HINT:3][RSV:2] = 24 bits

Field	Bits	Position	Description
MODE	1	23	Core (0) or Extended (1) mode
SRC	3	22-20	Source of the message
TYPE	3	19-17	Message type
INTENT	3	16-14	Sender's intent
DOMAIN	4	13-10	Application domain
SEC	2	9-8	Security level
PRIORITY	3	7-5	Message priority
ACTION_HINT	3	4-2	Expected action from receiver
RSV	2	1-0	Reserved for future use

Field Definitions

MODE (1 bit)

0 - Core Mode
1 - Extended Mode

SRC - Source (3 bits)

000 - Human
001 - AI Model
010 - System
011 - Sensor
100 - Hybrid
101 - External
110 - Unknown
111 - Reserved

TYPE (3 bits)

000 - Query
001 - Request
010 - Info
011 - Alert
100 - Command
101 - Comment
110 - Plan
111 - Emotion

INTENT (3 bits)

000 - Learn
001 - Request Action
010 - Command
011 - Warn
100 - Discuss
101 - Solve
110 - Inform
111 - Confirm

DOMAIN (4 bits)

0000 - General
0001 - Finance
0010 - Health
0011 - IoT
0100 - Software
0101 - AI
0110 - Education
0111 - Social
1000 - Legal
1001 - Security
1010 - Logistics
1011 - Energy
1100 - Commerce
1101 - Media
1110 - Science
1111 - Extended

SEC - Security (2 bits)

00 - Safe
01 - Suspicious
10 - Verified
11 - Unknown

PRIORITY (3 bits)

000 - None
001 - Low
010 - Normal
011 - High
100 - Urgent
101 - Critical
110 - Emergency
111 - Reserved

ACTION_HINT (3 bits)

000 - Info Only
001 - Interpretable
010 - Processing Required
011 - Response Expected
100 - Decision Required
101 - Action Required
110 - Urgent Action
111 - Reserved

Installation

No external dependencies required. Simply copy vibe_s.py to your project.

# Clone or download the repository
git clone <repository-url>
cd vibe-s

# Run tests
python test_vibe_s.py

Usage

Basic Encoding

from vibe_s import encode_vibe_s, Mode, Source, Type, Intent, Domain, Security, Priority, ActionHint

# Encode a message header
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(f"Encoded header: {header}")  # Integer value

Basic Decoding

from vibe_s import decode_vibe_s

# Decode a header
decoded = decode_vibe_s(header)

print(f"Source: {decoded['src_name']}")
print(f"Type: {decoded['type_name']}")
print(f"Domain: {decoded['domain_name']}")
print(f"Priority: {decoded['priority_name']}")

Format Conversions

from vibe_s import to_binary_string, to_hex, format_header

# Convert to binary string (24 chars)
binary = to_binary_string(header)
print(f"Binary: {binary}")

# Convert to hexadecimal
hex_value = to_hex(header)
print(f"Hex: {hex_value}")

# Format with field boundaries
formatted = format_header(header)
print(f"Formatted: {formatted}")

Display Header Information

from vibe_s import print_header_info

# Print complete header analysis
print_header_info(header, "Financial Transfer Command")

Example Scenarios

Scenario 1: Financial Transfer Command

Message: "Transfer 500 USD to account X"

Context: AI Model executing a financial transaction

header = encode_vibe_s(
    mode=Mode.CORE,
    src=Source.AI_MODEL,          # AI Model
    type_=Type.COMMAND,            # Command
    intent=Intent.COMMAND,         # Command
    domain=Domain.FINANCE,         # Finance
    sec=Security.SAFE,             # Safe
    priority=Priority.HIGH,        # High
    action_hint=ActionHint.ACTION_REQUIRED  # Action Required
)

Output:

Header (int): 2253680
Header (hex): 0x225F70
Binary: 001000100101111101110000

Scenario 2: IoT Sensor Data

Message: "Temperature is 28°C"

Context: Temperature sensor reporting current reading

header = encode_vibe_s(
    mode=Mode.CORE,
    src=Source.SENSOR,             # Sensor
    type_=Type.INFO,               # Info
    intent=Intent.INFORM,          # Inform
    domain=Domain.IOT,             # IoT
    sec=Security.SAFE,             # Safe
    priority=Priority.NORMAL,      # Normal
    action_hint=ActionHint.PROCESSING_REQUIRED  # Processing Required
)

Output: Output:

Header (int): 1875544
Header (hex): 0x1C9E48
Binary: 000111001001111001001000

Scenario 3: Suspicious Social Message

Message: "Click here for free money"

Context: Unknown source sending potentially malicious content

header = encode_vibe_s(
    mode=Mode.CORE,
    src=Source.UNKNOWN,            # Unknown
    type_=Type.REQUEST,            # Request
    intent=Intent.REQUEST_ACTION,  # Request Action
    domain=Domain.SOCIAL,          # Social
    sec=Security.SUSPICIOUS,       # Suspicious
    priority=Priority.LOW,         # Low
    action_hint=ActionHint.INFO_ONLY  # Info Only
)

Output:

Header (int): 3195456
Header (hex): 0x30C340
Binary: 001100001100001101000000

Running Tests

The test suite includes unit tests and scenario demonstrations:

# Run all tests with detailed output
python test_vibe_s.py

# Run only unit tests
python -m unittest test_vibe_s.TestVibesProtocol

Detailed Demonstration

For a step-by-step demonstration that shows exactly what gets encoded and decoded, run the detailed demo:

# Run detailed demonstration
python demo_vibe_s.py

This demonstration provides:

Complete encode/decode visualization for each scenario
Step-by-step breakdown of what happens during encoding
Binary field mapping showing which bits represent which fields
Verification that decode recovers the exact same values
Turkish language explanations for better understanding

Perfect for presentations, documentation, or learning how the protocol works internally!

API Reference

Core Functions

`encode_vibe_s(mode, src, type_, intent, domain, sec, priority, action_hint, rsv=0) -> int`

Encode VIBE-S protocol header to 24-bit integer.

Parameters:

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

`decode_vibe_s(header: int) -> dict`

Decode 24-bit VIBE-S header to dictionary.

Parameters:

header: 24-bit integer header

Returns: Dictionary with decoded fields and their names

`to_binary_string(header: int) -> str`

Convert 24-bit header to binary string representation.

Returns: 24-character binary string

`to_hex(header: int) -> str`

Convert 24-bit header to hexadecimal string.

Returns: 6-character hex string (with 0x prefix)

`format_header(header: int) -> str`

Format header with field boundaries for visualization.

Returns: Formatted binary string with field separators

`print_header_info(header: int, description: str = "")`

Print detailed header information including all decoded fields.

Design Principles

Ultra-Compact: Only 24 bits (3 bytes) overhead
Semantic Rich: Provides context about source, intent, domain, and required action
Security Aware: Built-in security level classification
Priority Support: 8 priority levels from None to Emergency
Machine Readable: Easy to parse and process by machines
Human Understandable: Clear field names and values

Use Cases

IoT Communication: Efficient sensor data transmission with context
AI Systems: Inter-AI communication with intent and domain information
Microservices: Lightweight service-to-service messaging
Edge Computing: Minimal overhead for resource-constrained devices
Security Systems: Built-in security classification for threat detection
Real-time Systems: Priority-based message handling

Benefits

Bandwidth Efficient: Only 3 bytes per message header
Low Latency: Fast encoding/decoding operations
Context Aware: Rich semantic information for intelligent routing
Security Classification: Immediate identification of suspicious content
Priority Routing: Support for priority-based message queuing
Extensible: Reserved bits and extended mode for future enhancements

Future Enhancements

Extended mode implementation for additional fields
Network protocol integration (TCP/IP, UDP, MQTT)
Hardware implementations for embedded systems
Compression algorithms for bulk transmission
Machine learning integration for automatic classification

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy...

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Contact

Uğur KANDEMİŞ ugurkandemis@aof.anadolu.edu.tr ugurkandemis@gmail.com

Version: 1.0.0 Last Updated: 2026-01-22

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
README.md		README.md
demo_vibe_s.py		demo_vibe_s.py
examples.py		examples.py
test_vibe_s.py		test_vibe_s.py
vibe_s.py		vibe_s.py

vibexcode/vibe-s

Folders and files

Latest commit

History

Repository files navigation