Metadata-Version: 2.4
Name: isagellm-protocol
Version: 0.1.0
Summary: sageLLM protocol types and validation (Protocol v0.1)
Author: IntelliStream Team
License: Proprietary - IntelliStream
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: ==3.11.*
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"

# sagellm-protocol

[![CI](https://github.com/your-org/sagellm-protocol/workflows/CI/badge.svg)](https://github.com/your-org/sagellm-protocol/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![Pydantic v2](https://img.shields.io/badge/pydantic-v2-e92063.svg)](https://docs.pydantic.dev/2.0/)

**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 类型检查通过

## 安装

```bash
pip install -e .
```

## 功能

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

## 使用示例

```python
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](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]

## 开发

### 快速开始

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

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

### 日常开发

```bash
# 运行测试
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

```bash
# 安装 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](.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](../../docs/internal/protocol_v0.1.md)

## 下游模块使用

### 如何在其他 sagellm 包中使用

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

```python
# 例如：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](../REPOS_README.md)

## License

Proprietary - IntelliStream
