isagellm-core 0.4.0.18__tar.gz → 0.4.0.19__tar.gz

isagellm_core-0.4.0.19/PKG-INFO

@@ -0,0 +1,718 @@
+Metadata-Version: 2.4
+Name: isagellm-core
+Version: 0.4.0.19
+Summary: sageLLM core runtime with PD separation (MVP)
+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
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: isagellm-protocol<0.5.0,>=0.4.0.0
+Requires-Dist: isagellm-backend<0.5.0,>=0.4.0.0
+Requires-Dist: isagellm-comm<0.5.0,>=0.4.0.0
+Requires-Dist: isagellm-kv-cache<0.5.0,>=0.4.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.22.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: transformers>=4.35.0
+Requires-Dist: accelerate>=0.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: isage-pypi-publisher>=0.2.0; extra == "dev"
+
+# sagellm-core
+
+![CI](https://github.com/intellistream/sagellm-core/actions/workflows/ci.yml/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/isagellm-core.svg)](https://pypi.org/project/isagellm-core/)
+[![Python](https://img.shields.io/pypi/pyversions/isagellm-core.svg)](https://pypi.org/project/isagellm-core/)
+[![License](https://img.shields.io/github/license/intellistream/sagellm-core.svg)](https://github.com/intellistream/sagellm-core/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+**sageLLM Core** 是一个硬件无关的 LLM 推理引擎，提供统一的推理接口（generate、stream、execute），支持自动后端选择（CPU/CUDA/Ascend），内置解码策略系统，并支持 PD 分离的混合模式执行。
+
+**版本**: `0.4.0.17` | **最后更新**: 2026-02-02 | **协议遵循**: [Protocol v0.1](https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/protocol_v0.1.md)
+
+## 📍 职责定位
+
+在整个 sageLLM 架构中的位置与职责：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  Application Layer                          │
+│        (sagellm-gateway, sagellm-control-plane)             │
+└────────────────┬────────────────────────────────────────────┘
+                 │
+┌────────────────┴────────────────────────────────────────────┐
+│  sagellm-core 本仓库                                         │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  LLMEngine: 硬件无关的统一推理入口                    │   │
+│  │  • generate() / stream() / execute()                 │   │
+│  │  • 自动后端选择 (cpu/cuda/ascend)                    │   │
+│  │  • Continuous Batching 调度                         │   │
+│  │  • 解码策略系统 (Greedy/Sampling/BeamSearch)        │   │
+│  │  • PD 分离混合模式执行                               │   │
+│  └──────────────────────────────────────────────────────┘   │
+├──────────────────────────────────────────────────────────────┤
+│  核心依赖 (L1 层)                                            │
+│  ├─ sagellm-backend: 硬件抽象、设备管理                    │
+│  ├─ sagellm-comm: 通信硬件、TP/PP 通信                     │
+│  ├─ sagellm-kv-cache: KV 缓存管理、驱逐策略              │
+│  └─ sagellm-protocol: 数据结构、错误定义                  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**职责边界**：
+- ✅ **Core 负责**: LLMEngine、调度、推理编排、解码策略
+- ✅ **Backend 负责**: 硬件抽象、设备管理、算子/内核
+- ✅ **Comm 负责**: 通信硬件抽象、集合操作、拓扑管理  
+- ✅ **Protocol 负责**: 全局共享的数据结构、错误码、ID 方案
+
+## ✨ 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| **统一推理接口** | `generate()` / `stream()` / `execute()` - 同步、流式、协议兼容 |
+| **硬件无关** | CPU/CUDA/Ascend - 自动检测与选择 |
+| **解码策略系统** | Greedy、Sampling、Beam Search、Contrastive Decoding |
+| **Continuous Batching** | 动态批处理，充分利用硬件 |
+| **PD 分离执行** | Prefill 和 Decode 阶段分离，支持混合模式 |
+| **配置驱动** | YAML/JSON 配置，Pydantic v2 验证 |
+| **HTTP Server** | FastAPI 实现，支持 SSE 流式传输 |
+| **CPU-First** | 完整支持无 GPU 环境，便于测试开发 |
+| **类型安全** | 完整的 Python 类型标注，Mypy 支持 |
+
+## 📦 依赖关系
+
+### 核心依赖（自动安装）
+
+```toml
+isagellm-protocol>=0.4.0.0,<0.5.0  # 协议定义
+isagellm-backend>=0.4.0.0,<0.5.0   # 硬件抽象
+isagellm-comm>=0.4.0.0,<0.5.0      # 通信后端
+isagellm-kv-cache>=0.4.0.0,<0.5.0  # KV 缓存管理
+
+# 框架依赖
+pydantic>=2.0.0      # 数据验证
+pyyaml>=6.0.0        # 配置解析
+torch>=2.0.0         # 张量计算
+transformers>=4.35.0 # 模型加载
+fastapi>=0.100.0     # HTTP 服务
+```
+
+### 谁依赖我
+
+- 🔵 **sagellm-control-plane**: 使用 Core 进行请求调度、负载均衡
+- 🟡 **sagellm-compression**: 建立在 Core 的模型执行层上
+- 🟢 **sagellm-gateway**: 提供 OpenAI 兼容 API
+
+## 🚀 安装指南
+
+### PyPI 安装（推荐）
+
+```bash
+# 安装最新版本
+pip install isagellm-core==0.4.0.17
+
+# 安装指定版本范围
+pip install "isagellm-core>=0.4.0.0,<0.5.0"
+```
+
+### 本地开发安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/intellistream/sagellm-core.git
+cd sagellm-core
+
+# 方式 1：一键安装（推荐）
+./quickstart.sh
+
+# 方式 2：手动安装开发环境
+pip install -e ".[dev]"
+
+# 安装 pre-commit hooks
+pre-commit install
+```
+
+### 本地链接依赖（用于本地多包开发）
+
+```bash
+# 如果同时在开发 backend/protocol/comm，使用本地版本
+pip install -e ../sagellm-protocol
+pip install -e ../sagellm-backend  
+pip install -e ../sagellm-comm
+pip install -e ../sagellm-kv-cache
+pip install -e ".[dev]"
+```
+
+### 验证安装
+
+```bash
+# 检查 package 版本
+python -c "import sagellm_core; print(sagellm_core.__version__)"
+
+# 运行快速测试
+pytest tests/test_ci_smoke.py -v
+```
+
+## 🎯 快速开始
+
+### 1. 基础推理
+
+```python
+from sagellm_core import LLMEngine, LLMEngineConfig
+
+# 创建配置
+config = LLMEngineConfig(
+    model_path="sshleifer/tiny-gpt2",  # HuggingFace 模型名或本地路径
+    backend_type="cpu",  # 自动选择 cpu/cuda/ascend
+    max_new_tokens=20
+)
+
+# 初始化引擎
+engine = LLMEngine(config)
+
+# 异步运行
+import asyncio
+
+async def main():
+    await engine.start()
+    
+    # 同步生成（完整输出）
+    response = await engine.generate("Hello, world!")
+    print(response.output_text)
+    
+    # 流式生成（逐 token 返回）
+    async for event in engine.stream("Once upon a time"):
+        if event.event == "delta":
+            print(event.chunk, end="", flush=True)
+    
+    await engine.stop()
+
+asyncio.run(main())
+```
+
+### 2. 使用采样参数控制生成
+
+```python
+from sagellm_core import LLMEngine, LLMEngineConfig
+from sagellm_protocol.sampling import SamplingParams, DecodingStrategy
+
+async def main():
+    config = LLMEngineConfig(model_path="sshleifer/tiny-gpt2")
+    engine = LLMEngine(config)
+    await engine.start()
+    
+    prompt = "The future of AI is"
+    
+    # 确定性输出（Greedy）
+    response = await engine.generate(
+        prompt,
+        sampling_params=SamplingParams(
+            strategy=DecodingStrategy.GREEDY,
+            max_tokens=20
+        )
+    )
+    print(f"Greedy: {response.output_text}")
+    
+    # 随机采样（Temperature 控制）
+    response = await engine.generate(
+        prompt,
+        sampling_params=SamplingParams(
+            strategy=DecodingStrategy.SAMPLING,
+            temperature=0.7,
+            top_p=0.9,
+            max_tokens=20
+        )
+    )
+    print(f"Sampling: {response.output_text}")
+    
+    await engine.stop()
+
+asyncio.run(main())
+```
+
+### 3. 从 YAML 配置文件运行 Demo
+
+```bash
+# 查看可用配置
+cat examples/config_cpu.yaml
+
+# 运行 Demo
+python -m sagellm_core.demo --config examples/config_cpu.yaml --verbose
+
+# 查看输出 metrics
+cat metrics.json
+```
+
+### 4. 启动 HTTP Server
+
+```bash
+# 方式 1：命令行
+sage-engine --host 0.0.0.0 --port 8000
+
+# 方式 2：Python API
+from sagellm_core import engine_server_app
+import uvicorn
+
+uvicorn.run(engine_server_app, host="0.0.0.0", port=8000)
+```
+
+### 5. HTTP 请求示例
+
+```bash
+# 同步推理
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt2",
+    "prompt": "Hello",
+    "max_tokens": 20
+  }'
+
+# 流式推理
+curl -X POST http://localhost:8000/v1/completions/stream \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt2",
+    "prompt": "Hello",
+    "max_tokens": 20,
+    "stream": true
+  }'
+```
+
+## 📚 API 文档
+
+### LLMEngine - 主入口
+
+**初始化**:
+```python
+LLMEngineConfig(
+    model_path: str,                # 必需：HuggingFace 名或本地路径
+    backend_type: str = "auto",     # 计算后端：cpu/cuda/ascend/auto
+    comm_type: str = "auto",        # 通信后端：gloo/nccl/hccl/auto
+    max_batch_size: int = 32,       # 最大批大小
+    max_model_len: int = 4096,      # 最大序列长度
+    max_new_tokens: int = 128,      # 每个请求最多生成 token 数
+    tensor_parallel_size: int = 1,  # 张量并行度
+    pipeline_parallel_size: int = 1, # 流水线并行度
+    dtype: str = "auto",             # 数据类型：float32/float16/bfloat16
+)
+```
+
+**关键方法**:
+```python
+async def start() -> None:
+    """启动引擎，加载模型"""
+
+async def stop() -> None:
+    """停止引擎，释放资源"""
+
+async def generate(
+    prompt: str | list[int],
+    *,
+    sampling_params: SamplingParams | None = None,
+    max_tokens: int | None = None,
+    request_id: str | None = None,
+) -> Response:
+    """同步推理，返回完整输出"""
+
+async def stream(
+    prompt_or_request: str | Request,
+    *,
+    max_tokens: int | None = None,
+    request_id: str | None = None,
+) -> AsyncIterator[StreamEvent]:
+    """流式推理，逐 token 返回事件"""
+
+async def execute(request: Request) -> Response:
+    """执行 Protocol Request，用于兼容旧接口"""
+```
+
+### SamplingParams - 采样参数
+
+```python
+from sagellm_protocol.sampling import SamplingParams, DecodingStrategy
+
+SamplingParams(
+    strategy: DecodingStrategy = DecodingStrategy.GREEDY,
+    temperature: float = 0.0,   # 越高越随机
+    top_p: float = 1.0,         # Nucleus 采样
+    top_k: int = 0,             # Top-K 采样
+    repetition_penalty: float = 1.0,
+    length_penalty: float = 1.0,
+    num_beams: int = 1,         # Beam Search 宽度
+    max_tokens: int = 128,
+    seed: int | None = None,    # 可复现性
+)
+```
+
+### 其他核心 API
+
+```python
+# 配置加载（Legacy）
+from sagellm_core import load_config
+config = load_config("config.yaml")  # 支持 YAML/JSON
+
+# 后端创建（Legacy）
+from sagellm_core import create_backend, BackendConfig
+backend = create_backend(BackendConfig(kind="cpu"))
+
+# 工厂方法（Legacy）
+from sagellm_core import EngineFactory
+factory = EngineFactory()
+engine = factory.create("cpu")  # 支持自动发现
+```
+
+## 🏗️ 架构设计
+
+### 分层架构
+
+```
+┌──────────────────────────────────┐
+│    LLMEngine (对外 API)           │  ← 用户交互层
+│  • generate/stream/execute       │
+└────────┬─────────────────────────┘
+         │
+┌────────▼──────────────────────────┐
+│    EngineCore (引擎核心)          │  ← 推理协调层
+│  • Scheduler: Continuous Batching │
+│  • Executor: 工作进程管理          │
+│  • KVCacheManager: 缓存管理        │
+└────────┬──────────────────────────┘
+         │
+┌────────▼──────────────────────────┐
+│    Worker & ModelRunner           │  ← 执行层
+│  • 前向传播                        │
+│  • TP/PP 通信                      │
+│  • 硬件资源管理                    │
+└────────┬──────────────────────────┘
+         │
+    ┌────┴────┬───────────┬────────────┐
+    ▼         ▼           ▼            ▼
+  Backend   Comm      KV-Cache     Protocol
+```
+
+### 模块说明
+
+| 模块 | 路径 | 职责 |
+|------|------|------|
+| **llm_engine** | `src/sagellm_core/llm_engine.py` | 统一推理入口 |
+| **engine_core** | `src/sagellm_core/engine_core/` | 调度与执行协调 |
+| **scheduler** | `src/sagellm_core/engine_core/scheduler.py` | Continuous Batching |
+| **executor** | `src/sagellm_core/executor/` | Worker 管理 |
+| **worker** | `src/sagellm_core/worker/` | 单设备执行 |
+| **decoding** | `src/sagellm_core/decoding/` | 5+ 种解码策略 |
+| **runtime** | `src/sagellm_core/runtime.py` | PD 分离 Runtime |
+| **pd_executor** | `src/sagellm_core/pd_executor.py` | Prefill/Decode 分离 |
+| **engine_server** | `src/sagellm_core/engine_server.py` | HTTP 服务 |
+
+## 🔧 开发指南
+
+### 项目结构
+
+```
+sagellm-core/
+├── src/sagellm_core/           # 源代码
+│   ├── llm_engine.py           # 统一推理引擎
+│   ├── engine_core/            # 引擎核心（调度+执行）
+│   ├── executor/               # Worker 执行器
+│   ├── worker/                 # Worker 和 ModelRunner
+│   ├── decoding/               # 解码策略（Greedy/Sampling/...)
+│   ├── engine_server.py        # HTTP Server (FastAPI)
+│   ├── config.py               # 配置类（Legacy）
+│   ├── factory.py              # 工厂方法（Legacy）
+│   ├── runtime.py              # PD 分离 Runtime
+│   ├── pd_executor.py          # PD 分离执行器
+│   └── ...
+├── tests/                      # 测试用例
+│   ├── unit/                   # 单元测试
+│   ├── integration/            # 集成测试
+│   ├── e2e/                    # 端到端测试
+│   └── conftest.py             # Pytest 配置
+├── examples/                   # 示例代码
+│   ├── config_cpu.yaml         # CPU 配置示例
+│   ├── config_cuda.yaml        # CUDA 配置示例
+│   ├── decoding_strategies_demo.py  # 解码策略演示
+│   ├── pd_separation_demo.py   # PD 分离演示
+│   └── ...
+├── docs/                       # 文档
+│   ├── ARCHITECTURE.md         # 详细架构
+│   ├── DECODING_STRATEGIES.md  # 解码策略指南
+│   └── ...
+├── pyproject.toml              # 项目配置（setuptools）
+├── pytest.ini                  # Pytest 配置
+├── .pre-commit-config.yaml     # Pre-commit hooks
+└── quickstart.sh               # 快速安装脚本
+```
+
+### 环境设置
+
+```bash
+# 克隆并进入项目
+git clone https://github.com/intellistream/sagellm-core.git
+cd sagellm-core
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 安装 git hooks（提交前自动检查）
+pre-commit install
+
+# 验证安装
+python -m pytest tests/test_ci_smoke.py -v
+```
+
+### 运行测试
+
+```bash
+# 运行所有测试
+pytest tests/ -v
+
+# 运行特定测试模块
+pytest tests/unit/test_config.py -v
+
+# 运行带覆盖率报告
+pytest tests/ --cov=sagellm_core --cov-report=html
+
+# 运行 slow 标记的测试（包括 LLM 测试）
+pytest tests/ -v -m slow
+
+# 运行单个测试用例
+pytest tests/test_llm_engine.py::test_engine_generate -v
+```
+
+### 代码质量检查
+
+```bash
+# Ruff 代码格式化 + Lint 检查
+ruff check . --fix       # 自动修复可修复的问题
+ruff format .            # 格式化代码
+
+# Mypy 静态类型检查
+mypy src/
+
+# 手动运行所有 pre-commit hooks
+pre-commit run --all-files
+
+# 运行特定 hook
+pre-commit run ruff --all-files
+pre-commit run mypy --all-files
+```
+
+### Git 提交流程
+
+1. **创建特性分支**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **提交代码（hooks 会自动检查）**
+   ```bash
+   git add .
+   git commit -m "feat: add your feature description"
+   ```
+   - 如果 hooks 失败，修复问题后重新提交
+   - 紧急情况：`git commit --no-verify` （不推荐）
+
+3. **推送并提 PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### 常见开发任务
+
+**添加新的解码策略**:
+1. 在 `src/sagellm_core/decoding/` 创建新文件
+2. 继承 `BaseDecodingStrategy`
+3. 实现 `__call__()` 方法
+4. 在 `__init__.py` 中导出
+5. 添加单元测试
+
+**添加新的后端支持**:
+1. 在 `sagellm-backend` 实现 BackendProvider
+2. 在 Core 中使用 `get_provider()` 自动发现
+3. 添加集成测试
+
+**添加配置选项**:
+1. 修改 `src/sagellm_core/config.py` 中的 Pydantic 模型
+2. 在示例配置文件中更新示例
+3. 更新文档和测试
+
+## 📖 示例代码
+
+### 完整的演示应用
+
+```bash
+# 运行解码策略完整演示（包含 6 个场景）
+python examples/decoding_strategies_demo.py
+
+# 运行 PD 分离演示
+python examples/pd_separation_demo.py
+```
+
+### CPU-First 测试
+
+所有测试默认在 CPU 上运行（无 GPU 要求）：
+
+```bash
+# 测试 LLMEngine
+pytest tests/test_engine.py -v
+
+# 测试配置系统
+pytest tests/test_config.py -v
+
+# 测试解码策略
+pytest tests/test_decoding_strategies.py -v
+
+# 测试 E2E 流程
+pytest tests/test_llm_engine_contract.py -v
+```
+
+### 模型下载
+
+使用提供的帮助脚本下载测试模型：
+
+```bash
+# 下载 tiny-gpt2（用于测试）
+python examples/model_download_helper.py
+
+# 或手动下载
+python -c "from transformers import AutoModel; AutoModel.from_pretrained('sshleifer/tiny-gpt2')"
+```
+
+## 🔄 持续集成
+
+本项目使用 GitHub Actions 进行 CI/CD：
+
+- **单元测试**: 每次 push 运行 `pytest tests/unit/`
+- **集成测试**: 每次 push 运行 `pytest tests/integration/`
+- **Lint 检查**: Ruff、Mypy、YAML 验证
+- **覆盖率**: 维持 >80% 的代码覆盖率
+
+查看 CI 配置：[.github/workflows/ci.yml](.github/workflows/ci.yml)
+
+## 📋 版本与变更
+
+**当前版本**: `0.4.0.17` (Alpha)
+
+**支持的 Python**: 3.10, 3.11, 3.12
+
+**完整变更日志**: 见 [CHANGELOG.md](CHANGELOG.md)
+
+**最近更新** (v0.4.0.17):
+- ✅ 采样参数标准化（issue #22）- 参数优先级系统
+- ✅ 增强解码策略测试
+- ✅ 完成 LLMEngine 与解码策略的集成测试
+- ✅ 解码策略使用演示与文档
+
+## 🤝 贡献指南
+
+我们欢迎社区贡献！请遵循以下步骤：
+
+1. **Fork** 仓库
+2. **创建特性分支** (`git checkout -b feature/your-feature`)
+3. **提交更改** (`git commit -m "feat: description"`)
+4. **推送到分支** (`git push origin feature/your-feature`)
+5. **提交 Pull Request**
+
+### 提交规范
+
+使用 Conventional Commits：
+```
+feat: 新增功能
+fix: 修复 bug
+docs: 文档更新
+test: 测试相关
+refactor: 代码重构
+perf: 性能优化
+```
+
+## 📄 许可证
+
+Proprietary - IntelliStream
+
+## 📞 反馈与支持
+
+- 📍 **GitHub Issues**: [提交问题](https://github.com/intellistream/sagellm-core/issues)
+- 💬 **讨论**: [启动讨论](https://github.com/intellistream/sagellm-core/discussions)
+- 📧 **Email**: team@intellistream.ai
+
+## 相关资源
+
+- 🔗 [Protocol v0.1 文档](https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/protocol_v0.1.md)
+- 🔗 [sagellm-backend](https://github.com/intellistream/sagellm-backend)
+- 🔗 [sagellm-comm](https://github.com/intellistream/sagellm-comm)
+- 🔗 [sagellm-kv-cache](https://github.com/intellistream/sagellm-kv-cache)
+- 🔗 [完整架构文档](docs/ARCHITECTURE.md)
+- 🔗 [解码策略指南](docs/DECODING_STRATEGIES.md)
+
+
+#### Continuous Integration
+
+GitHub Actions automatically runs on each PR:
+- Code linting and formatting checks
+- Tests across Python 3.10, 3.11, 3.12
+- Package build verification
+
+### Code Style
+
+This project uses:
+- **Ruff** for formatting and linting
+- **Mypy** for type checking
+- **Type hints** are required for all functions
+
+For detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+### 代码检查
+
+```bash
+# 格式化代码
+ruff format .
+
+# Lint 检查
+ruff check .
+
+# 类型检查
+mypy src/sagellm_core
+
+# 一键检查所有
+pre-commit run --all-files
+```
+
+## 依赖
+
+- `pydantic>=2.0.0`: 配置校验
+- `pyyaml>=6.0.0`: YAML 配置支持
+- `isagellm-protocol>=0.4.0.0,<0.5.0`: 协议定义
+- `isagellm-backend>=0.4.0.0,<0.5.0`: 后端抽象
+- `isagellm-comm>=0.4.0.0,<0.5.0`: 通信后端
+- `isagellm-kv-cache>=0.4.0.0,<0.5.0`: KV 缓存
+
+## Related Packages
+
+- `isagellm-protocol` - Protocol definitions (L0)
+- `isagellm-backend` - Backend abstraction layer (L1)
+- `isagellm-comm` - Communication abstraction (L1)
+- `isagellm-kv-cache` - KV Cache management (L1.5)
+- `sagellm-control-plane` - Cross-engine orchestration (L3)
+- `sagellm-gateway` - OpenAI-compatible API (L4)
+
+For the complete ecosystem, see [sageLLM organization](https://github.com/intellistream/sagellm)
+
+---
+
+**Last Updated**: 2026-02-02 | **Status**: Alpha (v0.4.0.17) | **Protocol**: v0.1
+