isagellm-protocol 0.1.0

sageLLM protocol types and validation (Protocol v0.1)

sagellm-protocol

sageLLM Protocol v0.1 - 类型定义和验证

这是 sageLLM 项目的基础协议包（Level 0），提供所有模块的公共契约。Protocol v0.1 的 Python types/校验（mock-first，CI 可无 GPU 运行）。

• 仓库名：sagellm-protocol
• PyPI 包名：isagellm-protocol
• import 名：sagellm_protocol

依赖层级定位

Level 0: sagellm-protocol ←─ 你在这里！（最基础，无依赖）
    ↓
Level 1: sagellm-backend (依赖 protocol)
    ↓
Level 2: sagellm-core (依赖 protocol + backend)
    ↓
Level 3: 功能模块（依赖 protocol + backend + core）
    ├─ sagellm-kv-cache
    ├─ sagellm-comm
    └─ sagellm-compression
    ↓
Level 4: sagellm-demo (依赖所有模块)

重要约束：

• ✅ 只依赖 pydantic>=2.0.0
• ❌ 不依赖 任何其他 sagellm 包
• ❌ 不依赖 任何推理/硬件 SDK（torch, CANN, NCCL 等）

本仓库只包含纯 Python 类型定义和 Pydantic 验证器，可在任何环境（包括无 GPU 的 CI）运行。

✅ Task0.01 完成状态

所有类型定义和测试已完成：

• ✅ errors.py - 错误类型定义（ErrorCode, Error）
• ✅ timestamps.py - 观测时间戳（Timestamps）
• ✅ kv_hooks.py - KV 生命周期钩子（KVAllocateParams, KVHandle, 等）
• ✅ types.py - 核心类型（Request, Response, Metrics, StreamEvent）
• ✅ init.py - 公共 API 导出
• ✅ 单元测试（39 个测试全部通过）
• ✅ ruff format/check 通过
• ✅ mypy 类型检查通过

安装

pip install -e .

功能

• ✅ Request/Response 类型定义
• ✅ Streaming 事件类型（start/delta/end）
• ✅ Metrics 类型定义（含校验器）
• ✅ 错误类型和错误码
• ✅ 观测时间戳
• ✅ KV 生命周期钩子类型
• ✅ Pydantic v2 验证
• ✅ Fail-fast 校验规则

使用示例

from sagellm_protocol import Request, Response, Metrics, ErrorCode

# 创建请求
req = Request(
    request_id="req-001",
    trace_id="trace-001",
    model="llama2-7b",
    prompt="Hello, world!",
    max_tokens=128,
    stream=False,
    temperature=0.7,
)

# 创建响应
metrics = Metrics(
    ttft_ms=45.2,
    tbt_ms=12.5,
    throughput_tps=80.0,
    peak_mem_mb=24576,
    error_rate=0.0,
)

resp = Response(
    request_id="req-001",
    trace_id="trace-001",
    output_text="Hi there!",
    output_tokens=[42, 17],
    finish_reason="stop",
    metrics=metrics,
)

更多示例见 examples/basic_usage.py。

导出的类型

核心类型

• Request - 请求对象
• Response - 响应对象
• Metrics - 性能指标

Streaming

• StreamEvent - 流式事件联合类型
• StreamEventStart - 开始事件
• StreamEventDelta - 增量事件
• StreamEventEnd - 结束事件

错误

• ErrorCode - 错误码枚举
• Error - 错误对象

观测

• Timestamps - 观测时间戳

KV 生命周期

• KVDType - KV Cache 数据类型
• KVLayout - KV Cache 内存布局
• KVAllocateParams - 分配参数
• KVHandle - KV 句柄
• KVEvictReason - 驱逐原因
• KVMigrateParams - 迁移参数

单位约定

根据 Protocol v0.1：

• 时间单位：毫秒（ms）
• 吞吐单位：tokens/sec
• 内存单位：MB
• 比率范围：0-1 浮点
• 字段命名：蛇形小写（snake_case）

校验规则

• max_tokens: 必须 > 0
• temperature: (0, 2]
• top_p: (0, 1]
• kv_budget_tokens: 若指定则 > 0
• Metrics: tbt_ms 和 tpot_ms 至少其一必须有值
• 所有比率字段（error_rate, prefix_hit_rate, spec_accept_rate）：[0, 1]

开发

快速开始

# 一键设置开发环境
./scripts/setup-dev.sh

# 或手动安装
pip install -e ".[dev]"
pre-commit install

日常开发

# 运行测试
pytest tests/ -v

# 带覆盖率测试
pytest tests/ -v --cov=sagellm_protocol --cov-report=term-missing

# 代码格式化
ruff format .

# 代码检查
ruff check . --fix

# 类型检查
mypy src/sagellm_protocol

# 运行所有 pre-commit 检查
pre-commit run --all-files

# 验证 Level 0 依赖要求
python scripts/verify_level0.py

Pre-commit Hooks

本项目使用 pre-commit hooks 确保代码质量：

• ruff format - 代码格式化
• ruff check - 代码 lint
• mypy - 严格模式类型检查
• Level 0 依赖检查 - 确保不引入禁止的依赖
• Protocol 字段命名检查 - 确保字段使用 snake_case

# 安装 hooks
pre-commit install

# 手动运行所有 hooks
pre-commit run --all-files

# 跳过慢速检查（本地开发时）
SKIP=mypy git commit -m "message"

CI/CD

每次 push 和 PR 都会自动运行：

1. lint - Ruff 格式和 lint 检查
2. typecheck - MyPy 严格模式类型检查
3. test - pytest 测试（Python 3.10/3.11/3.12）
4. verify-level0 - Level 0 依赖约束验证
5. build - 构建包并验证

详见 .github/workflows/ci.yml

Level 0 依赖要求验证：

• ✅ 只依赖 pydantic>=2.0.0
• ❌ 不依赖任何其他 sagellm 包
• ❌ 不依赖任何硬件 SDK（torch, CANN, NCCL 等）

运行 scripts/verify_level0.py 可自动检查这些约束。

协议版本

当前版本：v0.1

协议定义见：docs/internal/protocol_v0.1.md

下游模块使用

如何在其他 sagellm 包中使用

# 例如：sagellm-backend/pyproject.toml
dependencies = [
    "isagellm-protocol>=0.1.0,<0.2.0",  # 锁定小版本
]

# 例如：sagellm-backend 中的代码
from sagellm_protocol import (
    Request,
    Response,
    Metrics,
    Error,
    ErrorCode,
    KVAllocateParams,
    KVHandle,
)

# 使用协议定义的类型
def allocate_kv(params: KVAllocateParams) -> KVHandle:
    """实现 KV 分配逻辑"""
    ...

Protocol-First 开发流程

1. Week 1: Protocol v0.1 冻结并发布到 PyPI
2. Week 2-8: 各团队基于 isagellm-protocol==0.1.0 并行开发
3. 破坏性变更: 必须升级大版本（v0.2.0），并提供迁移指南

详见：REPOS_README.md

License

Proprietary - IntelliStream