metamessage 0.2.8

MetaMessage (mm) is a structured data exchange protocol. It is self-describing, self-constraining, and self-exemplifying, enabling lossless data exchange. It is designed as a next-generation universal protocol that natively supports AI, humans, and machines.

MetaMessage

MetaMessage (mm) is a structured data exchange protocol. It is self-describing, self-constraining, and self-exemplifying, enabling lossless data exchange. It is designed as a next-generation universal protocol that natively supports AI, humans, and machines.

• Human and AI friendly
• Export/import to JSONC (currently; YAML/TOML support planned)
• Suitable for configuration files and data exchange
• Works for traditional APIs and AI interaction scenarios
• Supports conversion between language structs/classes and MetaMessage
• Supports code generation for multiple languages
• Data carries type, constraint, description, and example without separate documentation
• All metadata can be updated with the data itself, without extra coordination
• Structures and values stay consistent across languages
• No structural loss; parsers adapt automatically and do not crash
• Can serialize to compact binary for faster decoding and smaller size

Problems solved

• Unknown types, such as not knowing whether a field is uint8
• Incomplete structure, such as null without inner type information
• No validation rules, so data legality cannot be checked
• No examples or descriptions, forcing reliance on separate docs
• Format changes require protocol adjustment and documentation resync

MetaMessage is naturally suited for AI understanding and interaction, solving ambiguity and imprecision in data. It replaces traditional API docs, verbal format agreements, and manual version sync by making data self-explanatory and independently evolvable.

pypi.org

github.com

功能特性

• 二进制编码/解码 — 将 Python 值高效编码为紧凑二进制格式
• @mm 装饰器 — 类似 Go 结构体标签的 Python 装饰器语法
• JSONC 支持 — 解析带 // mm: 注释的 JSON 格式
• Node 中间表示 — 通过 value_to_node / node_to_value 操作节点树
• 类型自动推断 — 根据 Python 类型注解自动推断 MetaMessage 类型
• 嵌套结构 — 支持字典、列表、类实例的递归转换

安装

pip 安装

pip install metamessage

版本要求

• Python 3.7 或更高版本

快速开始

基础编码/解码

from metamessage import encode_from_value, decode_to_value

# 编码 Python 值 → 二进制
binary = encode_from_value({"name": "Alice", "age": 30})
print(f"Encoded: {len(binary)} bytes")

# 解码二进制 → Python 值
result = decode_to_value(binary)
print(result)  # {'name': 'Alice', 'age': 30}

字符串/数字/布尔值

from metamessage import encode_from_value, decode_to_value

for val in ["hello", 42, 3.14, True, b"bytes"]:
    binary = encode_from_value(val)
    result = decode_to_value(binary)
    print(f"{val!r} → {result!r}")

@mm 装饰器

@mm 装饰器为 Python 类添加 MetaMessage 模式信息，类似 Go 的结构体标签。

mm 支持两种用法：

• 类级装饰器：@mm(desc="...") 放在 class 定义上方
• 字段级标记：field: type = mm(desc="...") 作为字段默认值（推荐）

类级 + 字段级装饰器（推荐）

from metamessage import mm, ValueType, encode_from_value, decode_to_value

@mm(desc="User information")
class User:
    id: int = mm(desc="User ID")
    name: str = mm(desc="User name")
    age: int = mm(desc="User age")

    def __init__(self, id: int = 0, name: str = "", age: int = 0):
        self.id = id
        self.name = name
        self.age = age

user = User(id=1, name="Alice", age=30)
binary = encode_from_value(user)
# binary -> {'id': 1, 'name': 'Alice', 'age': 30}

带类型和约束

@mm(desc="Product")
class Product:
    id: int = mm(desc="Product ID", type=ValueType.I64, min=1)
    name: str = mm(desc="Name", min=1, max=100)
    price: float = mm(desc="Price", min=0.0, max=999999.99)

    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
        self.id = id
        self.name = name
        self.price = price

仅类级装饰器

@mm(desc="User information")
class User:
    id: int
    name: str
    age: int

    def __init__(self, id: int = 0, name: str = "", age: int = 0):
        self.id = id
        self.name = name
        self.age = age

字符串标签语法

@mm("desc=Product; type=i64")
class Product:
    id: int
    name: str
    price: float

    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
        self.id = id
        self.name = name
        self.price = price

Node 中间表示

MetaMessage 使用 Node 树作为中间表示（IR）： T_CHILD_ENUM

节点类型	Python 类	描述
Val	值节点	存储标量值（字符串、数字、布尔等）
Obj	对象节点	键值对集合（对应 dict / 类实例）
Arr	数组节点	有序元素列表

value_to_node / node_to_value

from metamessage import value_to_node, node_to_value

# Python 值 → Node 树
node = value_to_node({"x": 10, "y": 20})

# Node 树 → Python 值
result = node_to_value(node, dict)
print(result)  # {'x': 10, 'y': 20}

手动构建 Node

from metamessage import Tag, ValueType, Obj, Arr, Val, Field, Encoder, Decoder

obj = Obj(
    fields=[
        Field(key="name", value=Val(data="John", text="John",
                                     tag=Tag(type=ValueType.Str))),
        Field(key="age", value=Val(data=30, text="30",
                                    tag=Tag(type=ValueType.I))),
    ],
    tag=Tag(name="person")
)

encoder = Encoder()
binary = encoder.encode(obj)
decoder = Decoder(binary)
result = decoder.decode()
print(result)  # {'name': 'John', 'age': 30}

JSONC 支持

JSONC 是带 // mm: 注释的 JSON 格式，用于声明模式标记：

解析 JSONC

from metamessage import parse_jsonc, to_jsonc

jsonc = """{
    // mm: type=str; desc=姓名
    "name": "Alice",
    // mm: type=i; desc=年龄
    "age": 30
}"""

node = parse_jsonc(jsonc)
for field in node.fields:
    print(f"{field.key}: type={field.value.tag.type}, desc={field.value.tag.desc}")

# 转回 JSONC 字符串
output = to_jsonc(node)
print(output)

JSONC -> 二进制 -> 解码

from metamessage import parse_jsonc, encode_from_value, decode_to_value

# 1. 解析 JSONC 获取 Node
node = parse_jsonc(jsonc_source)

# 2. 直接编码字典
binary = encode_from_value({"name": "Alice", "age": 30})

# 3. 解码
result = decode_to_value(binary)

完整示例

查看 examples/python/ 目录下的示例代码：

文件	说明
basic_encode_decode.py	基本编码/解码
dict_and_list.py	字典和列表操作
nested_structures.py	嵌套结构
mm_decorator.py	@mm 装饰器使用
jsonc_roundtrip.py	JSONC 完整流程
value_to_node_api.py	Node API 使用

运行示例：

# 在 mm-py 目录下
PYTHONPATH=. python3 examples/python/basic_encode_decode.py
PYTHONPATH=. python3 examples/python/dict_and_list.py
PYTHONPATH=. python3 examples/python/nested_structures.py

Tag 参数说明

基本参数

参数	类型	说明
type	ValueType	数据类型
desc	str	描述
nullable	bool	是否可空
allow_empty	bool	是否允许空值
default_val	str	默认值
raw	bool	是否原始模式
example	bool	是否为示例
unique	bool	是否唯一

约束参数

参数	适用类型	说明
min	int/float/bytes/string	最小值/长度
max	int/float/bytes/string	最大值/长度
size	array/bytes/string	固定大小
pattern	string	正则表达式
enums	enum	枚举值列表（"a|b|c"）
version	uuid/ip	版本号
mime	bytes	MIME 类型
location	datetime	时区偏移（-12 ~ +14）

子元素参数

参数	说明
child_type	子元素类型
child_desc	子元素描述
child_raw	子元素原始模式
child_nullable	子元素可空
child_allow_empty	子元素允许空值
child_unique	子元素唯一
child_default	子元素默认值
child_min	子元素最小值
child_max	子元素最大值
child_size	子元素大小
child_enum	子元素枚举
child_pattern	子元素模式
child_version	子元素版本
child_mime	子元素 MIME

API 参考

高层 API

函数	签名	说明
encode_from_value	(value: Any) -> bytes	Python 值 → 二进制
decode_to_value	(data: bytes, target_type=Any) -> Any	二进制 → Python 值
value_to_node	(value: Any, tag=None, depth=0, path="") -> Node	Python 值 → Node 树
node_to_value	(node: Node, target_type) -> Any	Node 树 → Python 值

核心类

类	说明
Encoder	编码器：Encoder().encode(node) -> bytes
Decoder	解码器：Decoder(data).decode() -> Any
Tag	模式标记：类型、约束、描述等
ValueType	类型枚举：String, Int, Float64, Bool 等

JSONC API

函数	签名	说明
parse_jsonc	(source: str) -> Node	解析 JSONC 字符串为 Node
to_jsonc	(node: Node) -> str	将 Node 转回 JSONC 字符串

装饰器

@mm(...) @mm(type=map) @mm(child_type=i8)

nullable 根據是否optional自動設置，只有optional的字段才可以設置is_null

类型	允许出现位置	语义	对应类型	允许标签
Obj	class	自定义结构体模型	自定义 MM 模型类	is_null example deprecated name desc allow_empty
Map	class	字典 键值集合	dict[K, V]	is_null example deprecated name type desc allow_empty
Vec	field	一维数组	list[T] [T]	is_null example deprecated name desc type allow_empty min max size unique 全部 child_* 子元素标签
Arr	field	固定长度数组	list[T] [T]	is_null example deprecated name desc allow_empty min max size unique 全部 child_* 子元素标签
Str	field	文本	str	is_null example deprecated name desc allow_empty min max size pattern
Bytes	field	二进制数据、文件、媒体流	bytes	is_null example deprecated name desc allow_empty min max size
Bool	field	真假状态	bool	is_null example deprecated name desc
I、I8、I16、I32、I64、U、U8、U16、U32、U64、Bigint	field	数字ID、数值、计数	int	is_null example deprecated name desc allow_empty min max size
F32	field	普通小数（非金额）	float	is_null example deprecated name desc allow_empty min max size
F64	field	普通小数（非金额）	float	is_null example deprecated name desc allow_empty min max size
Datetime	field	完整时间戳	datetime	is_null example deprecated name desc allow_empty min max location
Date	field	年月日	date	is_null example deprecated name desc allow_empty min max location
Time	field	时分秒	time	is_null example deprecated name desc allow_empty min max location
Uuid	field	唯一ID	str	is_null example deprecated name desc allow_empty min max size version
Decimal	field	Decimal	str	is_null example deprecated name desc allow_empty min max size
Ip	field	Ip	str	is_null example deprecated name desc allow_empty min max size version
Url	field	Url	str	is_null example deprecated name desc allow_empty min max size pattern
Email	field	Email	str	is_null example deprecated name desc allow_empty min max size pattern
Enums	field	状态、选项、固定枚举值	自定义 Enum 子类	is_null example deprecated name desc allow_empty enums
Media	field	图片 音视频 文件二进制	bytes	is_null example deprecated name desc allow_empty min max size mime

测试

# 运行主测试套件
python3 metamessage_test.py

# 运行分类测试
python3 tests/test_encoder.py
python3 tests/test_decoder.py
python3 tests/test_jsonc.py
python3 tests/test_value_to_node.py

uv run test
uv run python tests/test_mm.py 
uv run python tests/test_value_to_node.py 

许可

MIT