isagellm-core 0.1.0__cp311-none-any.whl

isagellm_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: isagellm-core
+Version: 0.1.0
+Summary: sageLLM core runtime (config/observability/registries), plugin-ready
+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.2.0,>=0.1.0
+Requires-Dist: isagellm-backend<0.2.0,>=0.1.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"
+
+# sagellm-core
+
+core 只依赖协议与抽象，不直接 import 硬件 SDK。
+
+- 仓库名：`sagellm-core`
+- PyPI 包名：`isagellm-core`
+- import 名：`sagellm_core`
+
+## 架构层级
+
+sagellm-core 位于 **Level 2**，依赖：
+- **Level 0**: `isagellm-protocol` (协议定义)
+- **Level 1**: `isagellm-backend` (后端抽象，包含 BackendProvider)
+
+为下游提供：
+- 配置体系（config.py）
+- Engine 抽象接口（engine.py）
+- 插件发现机制（plugins.py）
+- 工厂函数（factory.py）
+
+## 插件发现（entry points）
+
+- backends：`sagellm.backends`（由 sagellm-backend 提供基础实现）
+- engines：`sagellm.engines`（由各 engine 包提供实现）
+
+core 在运行时扫描 entry points；当配置指定 kind 但未安装插件时必须 fail-fast，并给出安装提示。
+
+## 配置系统（Task0.02）
+
+### 使用方法
+
+```python
+from sagellm_core import load_config, create_backend, create_engine
+
+# 从 YAML/JSON 加载配置
+config = load_config("config.yaml")
+
+# 创建 backend 和 engine（通过插件发现）
+backend = create_backend(config.backend)
+engine = create_engine(config.engine, backend)
+```
+
+### 配置结构
+
+所有配置类均使用 pydantic v2 实现严格校验：
+- 缺失必填字段立即抛出 `ValidationError`
+- 未知字段被拒绝（`extra="forbid"`）
+- 数值约束被强制执行
+
+主要配置类：
+- `BackendConfig`: 后端设备配置（kind, device, device_ids）
+- `EngineConfig`: 推理引擎配置（kind, model, model_path, 等）
+- `WorkloadConfig`: 工作负载配置（segments, concurrency, kv_budget_tokens, 等）
+- `OutputConfig`: 输出配置（metrics_path, report_path, log_path, log_level）
+- `MockConfig`: 模拟模式配置（enable, fixed_latency_ms, jitter_ms, error_rate）
+- `DemoConfig`: 顶层配置（包含以上所有配置 + 特性开关）
+
+### 配置示例
+
+#### 快速开始
+
+```bash
+# Mock 模式（无需 GPU）
+python -m sagellm.demo --config examples/config_mock.yaml
+
+# CUDA 生产模式
+python -m sagellm.demo --config examples/config_cuda.yaml
+
+# 昇腾生产模式
+python -m sagellm.demo --config examples/config_ascend.yaml
+```
+
+#### 示例配置文件
+
+- [config_mock.yaml](examples/config_mock.yaml) - Mock 模式（CI/开发）
+- [config_cuda.yaml](examples/config_cuda.yaml) - CUDA 生产模式
+- [config_ascend.yaml](examples/config_ascend.yaml) - 昇腾生产模式
+- [config_minimal.json](examples/config_minimal.json) - 最小 JSON 配置
+
+更多信息参见 [examples/README.md](examples/README.md)
+
+### 配置格式
+
+支持 YAML（推荐）和 JSON 格式：
+
+```yaml
+backend:
+  kind: mock
+engine:
+  kind: mock
+  model: mock-7b
+workload:
+  segments: [short, long, stress]
+  concurrency: 4
+output:
+  metrics_path: ./metrics.json
+```
+
+### 插件解析
+
+当配置指定的 backend/engine kind 未安装时，会抛出 `PluginResolutionError`：
+
+```python
+from sagellm_core import create_backend, BackendConfig, PluginResolutionError
+
+try:
+    backend = create_backend(BackendConfig(kind="ascend_cann", device="npu:0"))
+except PluginResolutionError as e:
+    print(f"错误: {e}")
+    # 输出: No implementation found for sagellm.backends kind='ascend_cann'.
+    #       Install hint: pip install isagellm-backend-ascend_cann
+```
+
+## Demo Runner CLI (Task0.08)
+
+sagellm-core 提供了 Demo Runner CLI，用于执行 Year1 Demo Contract 验证：
+
+### 用法
+
+```bash
+# 使用配置文件运行
+python -m sagellm_core.demo --config examples/demo_config.yaml
+
+# 强制使用 mock 模式（覆盖配置文件）
+python -m sagellm_core.demo --config config.yaml --mock
+
+# 覆盖 workload 段选择
+python -m sagellm_core.demo --config config.yaml --segments short,long
+
+# 覆盖输出路径
+python -m sagellm_core.demo --config config.yaml --output /tmp/metrics.json
+
+# 启用 streaming 模式和详细日志
+python -m sagellm_core.demo --config config.yaml --stream --verbose
+```
+
+### 示例配置
+
+参见 [examples/demo_config.yaml](examples/demo_config.yaml)：
+
+```yaml
+backend:
+  kind: mock
+  device: null
+
+engine:
+  kind: mock
+  model: mock-7b
+
+workload:
+  segments: [short, long, stress]
+  concurrency: 4
+  kv_budget_tokens: 8192
+
+output:
+  metrics_path: ./output/metrics.json
+  report_path: ./output/report.md
+```
+
+### 验收标准（Task0.08）
+
+- [x] `python -m sagellm_core.demo --help` 输出帮助信息
+- [x] `python -m sagellm_core.demo --config examples/demo_config.yaml --mock` 可运行
+- [x] 缺少 --config 参数时报错
+- [x] 配置文件不存在时报错
+- [x] 无效的 segment 值时报错
+- [x] `ruff check` 和 `mypy` 通过
+
+**注意**：实际 workload 执行逻辑在 task0_10 实现，当前阶段运行会输出 `NotImplementedError`。
+
+## 开发指南
+
+### 快速开始
+
+```bash
+# 克隆仓库
+git clone https://github.com/intellistream/sagellm-core.git
+cd sagellm-core
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 安装 pre-commit hooks
+pre-commit install
+
+# 验证环境
+pytest tests/ -v
+```
+
+### 质量保证体系
+
+sageLLM 实施三层质量保证：
+
+#### 1. Pre-commit Hooks（提交前自动检查）
+
+安装后，每次 `git commit` 会自动运行：
+- **Ruff**: 代码格式化 + Lint 检查
+- **Mypy**: 静态类型检查
+- **YAML/JSON**: 配置文件验证
+
+```bash
+# 手动运行所有 hooks
+pre-commit run --all-files
+
+# 绕过 hooks（紧急情况）
+git commit --no-verify
+```
+
+#### 2. 单元测试（本地验证）
+
+```bash
+# 运行所有测试
+pytest tests/ -v
+
+# 运行特定模块测试
+pytest tests/unit/test_demo.py -v
+pytest tests/unit/test_config.py -v
+
+# 生成覆盖率报告
+pytest tests/ --cov=sagellm_core --cov-report=html
+open htmlcov/index.html
+```
+
+测试要求：
+- ✅ 新功能必须有对应单元测试
+- ✅ 覆盖率不低于现有水平
+- ✅ 所有测试必须支持 mock 模式（无需 GPU）
+
+#### 3. CI/CD（自动化验证）
+
+每次 PR 触发 GitHub Actions 自动运行：
+- **Lint Job**: Ruff + Mypy 检查
+- **Test Job**: 多 Python 版本矩阵测试（3.10, 3.11, 3.12）
+- **Protocol Job**: 验证与 Protocol v0.1 对齐
+- **Build Job**: 验证包构建
+
+查看 CI 状态：`.github/workflows/ci.yml`
+
+### 代码规范
+
+**核心原则**：
+1. **Protocol-first** - 修改接口前先升级 Protocol
+2. **Mock-first** - 所有模块支持 mock 模式
+3. **Fail-fast** - 禁止隐式默认值，配置错误立即报错
+4. **Type-safe** - 所有函数必须有类型注解
+
+```python
+# ✅ 正确示例
+def create_backend(config: BackendConfig) -> BaseBackend:
+    if config.kind == "mock":
+        return MockBackend(config)
+    raise PluginResolutionError(f"Unknown backend: {config.kind}")
+
+# ❌ 错误示例
+def create_backend(config):  # 缺少类型注解
+    return MockBackend(config.get("kind", "mock"))  # 隐式默认值
+```
+
+详细规范参见 [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.1.0,<0.2.0`: 协议定义（Level 0）
+- `isagellm-backend>=0.1.0,<0.2.0`: 后端抽象（Level 1）
+
+## 依赖层级说明
+
+```
+Level 0: isagellm-protocol (最基础，无依赖)
+    ↓
+Level 1: isagellm-backend (依赖 protocol)
+    ↓
+Level 2: isagellm-core (依赖 protocol + backend) ← 当前包
+    ↓
+Level 3: 功能模块（依赖 protocol + backend + core）
+    ├─ isagellm-kv-cache
+    ├─ isagellm-comm
+    └─ isagellm-compression
+    ↓
+Level 4: isagellm-demo (依赖所有模块)
+```
+

isagellm_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+sagellm_core/__init__.py,sha256=MWpaRuB3qnlJMWGEg-WRgcIilMTO8KYzuenfc95Gy2o,1427
+sagellm_core/__init__.pyc,sha256=UmPe4uUGaK75yWKog9QSNWBRUoYvNN21iMTzucPznzM,1538
+sagellm_core/__main__.pyc,sha256=48Ej1ycqV-z87qawGOTNBKNgY3EcbffUOOXrDecOR3g,384
+sagellm_core/config.pyc,sha256=Reg92lld5VRC8FcV3qahAXaWmwar5RYfQMLysPw5UFQ,9617
+sagellm_core/demo.pyc,sha256=hI3RKeIGhmoKt7N30r5QWJh07qrmf49cZlXjp48phz4,5728
+sagellm_core/engine.pyc,sha256=4HFROkpRES11m5dQyOjyYRA0RbJFlYO2Dl7A5dMu9_w,3598
+sagellm_core/factory.pyc,sha256=uLXID49VZ7TcNZqgLBbznInCXjwbRSXSpD0bc6WHDVs,2692
+sagellm_core/mock_engine.pyc,sha256=wTAEID7SVpZGeMiujX98CumNksp4T78AfKIWeuCb2jI,532
+sagellm_core/plugins.pyc,sha256=RwUFT48AJhKqah3q7YOigOYwqvnei6RNMqpZksX5VJ0,2618
+sagellm_core/py.typed,sha256=ixa8YukDZ3kLo0WsFJRGohLMyHzbMur1ALmmASML2cs,64
+sagellm_core/runner.pyc,sha256=1E0hkYDYxQFSXUrTxALP7kvwX8Z1-jsRfyzWumC2cKE,14479
+sagellm_core/workload.pyc,sha256=92TRxjcnKLzAbcVZgOTPzwdR9dU1hqjO2j-olr1QCQ8,4118
+sagellm_core/__pycache__/__init__.cpython-311.pyc,sha256=vEYsS7efRG35E0lrTNCLokWRUGaE8DINcT2LRqabs_s,1582
+sagellm_core/__pycache__/config.cpython-311.pyc,sha256=bFTIjHE0DP304V_cvsFREkedx1b9TB4UTVDwExUvqXo,9661
+sagellm_core/__pycache__/demo.cpython-311.pyc,sha256=dG2EDA_mTwWRgOWujyDXJvDAInQZWuNgJOBTMxtkxQc,5772
+sagellm_core/__pycache__/engine.cpython-311.pyc,sha256=TCUxrAN856WYtEzi4D1tXNjgj177Cx6d2yp2LMMcC7I,3647
+sagellm_core/__pycache__/factory.cpython-311.pyc,sha256=d3up_zYRL1q12mGYvBE_f6HpzaWlerXV_RZ9ys4VZtQ,2736
+sagellm_core/__pycache__/mock_engine.cpython-311.pyc,sha256=zCHNncwIzEgqZ0lc7kiWkS-zOHf7CQ73UhCXztR6mFM,581
+sagellm_core/__pycache__/plugins.cpython-311.pyc,sha256=__NNjLfUJXa1DqwdgVBJAkLp-nN2rcA5SXM0_Jd9MPU,2662
+sagellm_core/__pycache__/runner.cpython-311.pyc,sha256=dCWo6RBDeeQFj3Igh0A6P6LKUH7r3w9sStqXChypXRo,14523
+sagellm_core/__pycache__/workload.cpython-311.pyc,sha256=kOSkfzgj2-GozzyuTfTE7NST2_HblneakPUuj9MLP48,4162
+sagellm_core/engines/__init__.py,sha256=X_zrzK96ZTwcqWJD6GcdZ_9cynsJnpN11KtV_GQTG4c,248
+sagellm_core/engines/__init__.pyc,sha256=wvPx_2E1evtbKxyF7d1xdoK5l-XVLh7_vkFlKkf8KtI,458
+sagellm_core/engines/mock.pyc,sha256=7V2PgGvtuEsAU8sW5D9ZEIj0NpcqnTy2ezSDQw_C_Q4,7917
+sagellm_core/engines/__pycache__/__init__.cpython-311.pyc,sha256=5EYPxOv12AZEhUSw_v65GgVskdxzcJLcfdhJ5B05BHw,502
+sagellm_core/engines/__pycache__/mock.cpython-311.pyc,sha256=YpY2M-rXF_vMg0GeWfPnrqo06KL-gHrbBAF-1nh3wUQ,7961
+isagellm_core-0.1.0.dist-info/METADATA,sha256=5LT4nsoDr8tF4SriE5hBLtA9SigJSxuaQxwYDhSNIO0,8631
+isagellm_core-0.1.0.dist-info/WHEEL,sha256=27snaH8EChr9VGIQt_981R5IOTPR-vQPuJNW-WzhNJA,93
+isagellm_core-0.1.0.dist-info/entry_points.txt,sha256=dvRi6CIfghSFY6qmzpfG6nLg9yeQicW6lFBTNmdgEB8,70
+isagellm_core-0.1.0.dist-info/top_level.txt,sha256=wcgdWrvkaoYYh_dWSFI5Toi8PZsHutVqfhTB2tb0K6g,13
+isagellm_core-0.1.0.dist-info/RECORD,,

isagellm_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: cp311-none-any
+

isagellm_core-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sagellm.engines]
+mock = sagellm_core.engines.mock:create_mock_engine

isagellm_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sagellm_core

sagellm_core/__init__.py

@@ -0,0 +1,61 @@
+"""sageLLM Core 运行时。
+
+本包提供 sageLLM 的核心运行时组件：
+- 配置 schema 与校验
+- Engine 抽象接口与实现
+- Backend 与 Engine 工厂函数
+- 插件系统
+- Demo Runner
+"""
+
+from __future__ import annotations
+
+from sagellm_core.config import (
+    BackendConfig,
+    DemoConfig,
+    EngineConfig,
+    MockConfig,
+    OutputConfig,
+    WorkloadConfig,
+    WorkloadSegment,
+    load_config,
+)
+from sagellm_core.demo import main as demo_main
+from sagellm_core.engine import BaseEngine, HealthStatus
+from sagellm_core.engines.mock import MockEngine, create_mock_engine
+from sagellm_core.factory import create_backend, create_engine
+from sagellm_core.plugins import PluginResolutionError, list_entry_points, resolve_kind
+from sagellm_core.runner import DemoRunner, RunnerContext
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Configuration
+    "BackendConfig",
+    "DemoConfig",
+    "EngineConfig",
+    "MockConfig",
+    "OutputConfig",
+    "WorkloadConfig",
+    "WorkloadSegment",
+    "load_config",
+    # Engine abstraction
+    "BaseEngine",
+    "HealthStatus",
+    # Engine implementations
+    "MockEngine",
+    "create_mock_engine",
+    # Factory functions
+    "create_backend",
+    "create_engine",
+    # Plugin system
+    "PluginResolutionError",
+    "list_entry_points",
+    "resolve_kind",
+    # Demo runner
+    "demo_main",
+    "DemoRunner",
+    "RunnerContext",
+]

sagellm_core/engines/__init__.py

@@ -0,0 +1,13 @@
+"""Engine implementations
+
+包含各种引擎实现（mock, adapters 等）。
+"""
+
+from __future__ import annotations
+
+from sagellm_core.engines.mock import MockEngine, create_mock_engine
+
+__all__ = [
+    "MockEngine",
+    "create_mock_engine",
+]

sagellm_core/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This package supports type checking