isagellm-core 0.2.2.6__py2.py3-none-any.whl

isagellm_core-0.2.2.6.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: isagellm-core
+Version: 0.2.2.6
+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.3.0,>=0.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: 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
+
+## Protocol Compliance (Mandatory)
+
+- MUST follow Protocol v0.1: https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/protocol_v0.1.md
+- Any globally shared definitions (fields, error codes, metrics, IDs, schemas) MUST be added to Protocol first.
+
+[![CI](https://github.com/intellistream/sagellm-core/actions/workflows/ci.yml/badge.svg)](https://github.com/intellistream/sagellm-core/actions/workflows/ci.yml)
+[![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 - 引擎协调层与运行时系统
+
+## 架构定位
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  sagellm-core (引擎协调层) ← 本仓库                         │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  Engine Abstraction (BaseEngine, EngineFactory)    │    │
+│  │  • CPUEngine, HFCudaEngine                         │    │
+│  │  • 自描述架构 (is_available, priority)              │    │
+│  │  • 引擎自动发现与注册                                │    │
+│  └─────────────────────────────────────────────────────┘    │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  Configuration System (config.py)                  │    │
+│  │  • YAML/JSON 配置解析                               │    │
+│  │  • Pydantic v2 类型验证                            │    │
+│  └─────────────────────────────────────────────────────┘    │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  Demo Runner (runner.py)                           │    │
+│  │  • 协调 backend + engine + workload                │    │
+│  │  • M1 Demo Contract 验证                           │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│  sagellm-backend (硬件抽象层)                               │
+│  • BackendProvider (CPU/CUDA/Ascend)                       │
+│  • Stream/Event/KVBlock 管理                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**职责分离**：
+- ❌ **Backend 不再包含**：BaseEngine, EngineFactory（已移至 core）
+- ✅ **Core 负责**：引擎接口、工厂、运行时、配置、协调
+- ✅ **Backend 负责**：硬件抽象、设备管理、内存原语
+
+## Features
+
+- 🔧 引擎抽象层与自描述架构
+- 🏭 EngineFactory - 支持自动发现与优先级选择
+- 🎯 内置引擎实现（CPU/CUDA/Embedding）
+- 🔌 插件系统 - 扩展引擎与后端
+- 📊 Demo Runner - M1 验证框架
+- ⚙️ 配置系统 - YAML/JSON + Pydantic v2
+- ✅ CPU-First - 无 GPU 测试支持
+
+## 安装
+
+```bash
+# 从 PyPI 安装（自动安装 protocol + backend 依赖）
+pip install isagellm-core
+```
+
+## 🚀 开发者快速开始
+
+```bash
+git clone git@github.com:intellistream/sagellm-core.git
+cd sagellm-core
+./quickstart.sh   # 一键安装开发环境（含依赖）
+
+# 或手动安装
+pip install -e ".[dev]"
+```
+
+运行测试：
+```bash
+pytest tests/ -v
+```
+
+运行 Demo（CPU 模式）：
+```bash
+python -m sagellm_core.demo --segments short
+```
+
+> 💡 **提示**：`isagellm-protocol` 和 `isagellm-backend` 会自动从 PyPI 安装。
+> 如需本地联调：
+> ```bash
+> pip install -e ../sagellm-protocol
+> pip install -e ../sagellm-backend
+> ```
+
+## Configuration System
+
+### 使用方法
+
+```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)
+```
+
+### Configuration Structure
+
+Main configuration components:
+- `BackendConfig`: Device and backend settings
+- `EngineConfig`: Inference engine configuration
+- `WorkloadConfig`: Workload parameters
+- `OutputConfig`: Output paths and logging
+- `DemoConfig`: Top-level demo configuration
+
+### 配置示例
+
+#### 快速开始
+
+```bash
+# CPU 模式（无需 GPU）
+python -m sagellm.demo --config examples/config_cpu.yaml
+
+# CUDA 生产模式
+python -m sagellm.demo --config examples/config_cuda.yaml
+
+# 昇腾生产模式
+python -m sagellm.demo --config examples/config_ascend.yaml
+```
+
+#### 示例配置文件
+
+- [config_cpu.yaml](examples/config_cpu.yaml) - CPU 模式（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: cpu
+engine:
+  kind: cpu
+  model: sshleifer/tiny-gpt2
+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，用于执行 M1 Demo Contract 验证：
+
+### 用法
+
+```bash
+# 使用配置文件运行
+python -m sagellm_core.demo --config examples/demo_config.yaml
+
+# 强制使用 CPU 模式（覆盖配置文件）
+python -m sagellm_core.demo --config config.yaml --backend cpu
+
+# 覆盖 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: cpu
+  device: cpu
+
+engine:
+  kind: cpu
+  model: sshleifer/tiny-gpt2
+
+workload:
+  segments: [short, long, stress]
+  concurrency: 4
+  kv_budget_tokens: 8192
+
+output:
+  metrics_path: ./output/metrics.json
+  report_path: ./output/report.md
+```
+
+## Development Guide
+
+### 快速开始
+
+```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
+```
+
+### Testing and Quality
+
+#### Pre-commit Hooks
+
+安装后，每次 `git commit` 会自动运行：
+- **Ruff**: 代码格式化 + Lint 检查
+- **Mypy**: 静态类型检查
+- **YAML/JSON**: 配置文件验证
+
+```bash
+# 手动运行所有 hooks
+pre-commit run --all-files
+
+# 绕过 hooks（紧急情况）
+git commit --no-verify
+```
+
+#### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test module
+pytest tests/unit/test_demo.py -v
+
+# Generate coverage report
+pytest tests/ --cov=sagellm_core --cov-report=html
+```
+
+#### 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.1.0,<0.2.0`: 协议定义（Level 0）
+- `isagellm-backend>=0.1.0,<0.2.0`: 后端抽象（Level 1）
+
+## Related Packages
+
+- `isagellm-protocol` - Protocol definitions
+- `isagellm-backend` - Backend abstraction layer
+- `isagellm` - Main package with CLI
+
+For more packages, see the [sageLLM ecosystem](https://github.com/intellistream/sagellm)

isagellm_core-0.2.2.6.dist-info/RECORD

@@ -0,0 +1,44 @@
+sagellm_core/__init__.py,sha256=gduyaxWfhS2iepRxovlk11u2nlseqxxs8jVOkkMd-Qw,2798
+sagellm_core/__init__.pyc,sha256=j_6Q0GNFJX4705JJ8g5P66TYAgHF4FLbZ6npPxL6-08,2758
+sagellm_core/__main__.pyc,sha256=48Ej1ycqV-z87qawGOTNBKNgY3EcbffUOOXrDecOR3g,384
+sagellm_core/config.pyc,sha256=cCMLvMVb_s3HzPYSfqlbRWodQ4Uby8U962l1vmunT5Y,8453
+sagellm_core/demo.pyc,sha256=0hZkAJch6ETjSDsPq8XkDLNcd8qAys_hqOH1qi0xBzg,6028
+sagellm_core/engine.pyc,sha256=VJMpwWH8Dlem1Q54MlQrGNEs54TTFYpNu6KoJkkgFwY,9748
+sagellm_core/engine_factory.pyc,sha256=cNbEImM0MNcCgVeC0zViAT1AZkPAt2WARrVd1U__tS4,14886
+sagellm_core/factory.pyc,sha256=B0s_JSOjVPwE95Oj2moP_vVA3vCrWsi2753UrwF8-eM,2737
+sagellm_core/health.pyc,sha256=c4A60b1ZANbAqck59AV-kczK2b355EPi9JxoYHRlhl8,684
+sagellm_core/plugins.pyc,sha256=g6eke_yH65_7Bu6yfT7v19cZ7gjIAWbkyG7gv1JSXy0,2617
+sagellm_core/py.typed,sha256=ixa8YukDZ3kLo0WsFJRGohLMyHzbMur1ALmmASML2cs,64
+sagellm_core/runner.pyc,sha256=GK_t15IH2etN6flRqUui4iUPkD39zl3_rw1wnOSG5Jg,14238
+sagellm_core/workload.pyc,sha256=G9yMm2L4ZyZpGsCxuEOQ83t78Y_lCQmbg5p6OHl5rn0,4127
+sagellm_core/__pycache__/__init__.cpython-311.pyc,sha256=gm2FQIQMHojIxuM5DWyupCubtTsxXzjQLfMwyrwtVEk,2788
+sagellm_core/__pycache__/base_engine.cpython-311.pyc,sha256=XiynMTxG3srYsUwzIoEbwEJOmpjBBB6UNEoAXDxDgWM,9563
+sagellm_core/__pycache__/config.cpython-311.pyc,sha256=6gUdzUs3m31zGQVa2OzlPcPbX1it2Ziag0cQbCaXvIU,8483
+sagellm_core/__pycache__/demo.cpython-311.pyc,sha256=PN6yZ3PgPWjiZ4XqpqRT-s5YYWitMwR_muYFvPmXdWA,6058
+sagellm_core/__pycache__/engine.cpython-311.pyc,sha256=sEEWFk9NHq8l9Q8NKvSQbomRJx2vMdjvtVUiGKx62jM,9778
+sagellm_core/__pycache__/engine_factory.cpython-311.pyc,sha256=Qte3LXKSpcOWGhu-Hns7xPvTdkyYry3v_EeYQbfVp4w,14916
+sagellm_core/__pycache__/factory.cpython-311.pyc,sha256=R4MbGyreD3U2iWmwQ0r14R347GAY9RM_I1xOiWovozo,2767
+sagellm_core/__pycache__/health.cpython-311.pyc,sha256=Z2mo-4iGINZp0w9AmCJomhHGRSzvbwxCfmdMAjg5vc4,714
+sagellm_core/__pycache__/mock_engine.cpython-311.pyc,sha256=zCHNncwIzEgqZ0lc7kiWkS-zOHf7CQ73UhCXztR6mFM,581
+sagellm_core/__pycache__/plugins.cpython-311.pyc,sha256=gaoaHApylGSrmMxXVwFs2v4idiZJnisttawlXTbXBWY,2647
+sagellm_core/__pycache__/runner.cpython-311.pyc,sha256=krW5MagsiQcX5J9fljblEshfsQB_gAIAWR7S0uD-TzU,14268
+sagellm_core/__pycache__/workload.cpython-311.pyc,sha256=Y01UUCDE85D8GY5kF_UsHyNCBbMkmsoB3vOUJV-vulA,4157
+sagellm_core/engines/__init__.py,sha256=9XyjgaAl6nR3uMSx4EzBQqQ1wE7jQfpR_k69083EZOY,1068
+sagellm_core/engines/__init__.pyc,sha256=2Sh_n2W0ZidghYCT7t0N0RfPZhqVjfhWWEdohNyBBNw,1118
+sagellm_core/engines/cpu.pyc,sha256=_PPwKyYmhSRNg7SjRJ3m5jOmjBV9qjVAvono3502lFI,20109
+sagellm_core/engines/embedding.pyc,sha256=Be4To-qpamFuGcyFZ1MKPk6XOf_HDBKnBGoIisxNemE,11476
+sagellm_core/engines/hf_cuda.pyc,sha256=HTOtHVyX6dbysMc5Lx9DeJpE6rSTG2CQcIn0xb0rcBI,50340
+sagellm_core/engines/pytorch.pyc,sha256=MLcymoDnwMduWoWVDZmYuG6UoQavNO-FjddPQ8ccccI,18408
+sagellm_core/engines/pytorch_engine.pyc,sha256=fdzf-VN2hVRWzP8PCmGV-pg9qUIJWWqEH662CRmh5_0,11645
+sagellm_core/engines/__pycache__/__init__.cpython-311.pyc,sha256=t289gZVTllHWt7jXYL31Cs3CHNgd84Yl6FrEiywxiso,1148
+sagellm_core/engines/__pycache__/cpu.cpython-311.pyc,sha256=c53zodjzFJu1s-Enyum9cj_Zi2ENr1W3xgsNG_13gHE,20139
+sagellm_core/engines/__pycache__/embedding.cpython-311.pyc,sha256=ZNqFpuCsS4Wp0xg7yV3GBbaJ4G0saqGNaKMdivxEBkA,11506
+sagellm_core/engines/__pycache__/hf_cuda.cpython-311.pyc,sha256=1YYE_6xLS9Gqg5O2hrg07IbaVfXhC6SBQBLH31xowJw,50370
+sagellm_core/engines/__pycache__/mock.cpython-311.pyc,sha256=1g9YyKfo9yv-6VTjzzfacv-9ZICHjsVXjyJ_IajRnQo,14641
+sagellm_core/engines/__pycache__/pytorch.cpython-311.pyc,sha256=MRSQN2ZBJmuIxFIA_yflaxarFhslfT0SG0Lw7-EFyDQ,18438
+sagellm_core/engines/__pycache__/pytorch_engine.cpython-311.pyc,sha256=dLBcBODxEqgmH25nCBPWhwy3uu3-dqzyzOwQy-izN7A,11675
+isagellm_core-0.2.2.6.dist-info/METADATA,sha256=_NR4IGCdsRHDZci0NvDFA62Vh9dLjcsbDqHaF4MME-Y,10811
+isagellm_core-0.2.2.6.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+isagellm_core-0.2.2.6.dist-info/entry_points.txt,sha256=GOAxUrzSeJyOUjseRjJwhNLu8oLEMlbszb4j8xyr2QY,128
+isagellm_core-0.2.2.6.dist-info/top_level.txt,sha256=wcgdWrvkaoYYh_dWSFI5Toi8PZsHutVqfhTB2tb0K6g,13
+isagellm_core-0.2.2.6.dist-info/RECORD,,

isagellm_core-0.2.2.6.dist-info/WHEEL

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

isagellm_core-0.2.2.6.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[sagellm.engines]
+cpu = sagellm_core.engines.cpu:create_cpu_engine
+pytorch = sagellm_core.engines.pytorch:create_pytorch_engine

isagellm_core-0.2.2.6.dist-info/top_level.txt

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

sagellm_core/__init__.py

@@ -0,0 +1,114 @@
+"""sageLLM Core 运行时。
+
+本包提供 sageLLM 的核心运行时组件：
+- 配置 schema 与校验
+- Engine 抽象接口与实现
+- Engine 工厂函数
+- 插件系统
+- Demo Runner
+"""
+
+from __future__ import annotations
+
+from sagellm_core.engine import BaseEngine, EngineInstanceConfig
+from sagellm_core.config import (
+    BackendConfig,
+    DemoConfig,
+    EngineConfig,
+    OutputConfig,
+    WorkloadConfig,
+    WorkloadSegment,
+    load_config,
+)
+from sagellm_core.demo import main as demo_main
+from sagellm_core.engine_factory import EngineFactory
+from sagellm_core.engines import (
+    CPUEngine,
+    EmbeddingEngine,
+    EmbeddingEngineConfig,
+    HFCudaEngine,
+    HFCudaEngineConfig,
+)
+from sagellm_core.factory import create_backend, create_engine
+from sagellm_core.health import HealthStatus
+from sagellm_core.plugins import PluginResolutionError, list_entry_points, resolve_kind
+from sagellm_core.runner import DemoRunner, RunnerContext
+
+# PyTorch engine (optional, loaded lazily)
+PyTorchEngine = None
+PyTorchEngineConfig = None
+PyTorchEngineInstanceConfig = None
+create_pytorch_engine = None
+
+try:
+    from sagellm_core.engines.pytorch import (
+        PyTorchEngine,
+        PyTorchEngineConfig,
+        PyTorchEngineInstanceConfig,
+        create_pytorch_engine,
+    )
+except ImportError:
+    pass  # torch or transformers not available
+
+# Auto-register built-in engines (conditional for optional dependencies)
+try:
+    EngineFactory.register(CPUEngine)
+except Exception:
+    pass  # torch not available
+
+try:
+    EngineFactory.register(HFCudaEngine)
+except Exception:
+    pass  # torch or CUDA not available
+
+try:
+    EngineFactory.register(EmbeddingEngine)
+except Exception:
+    pass  # sentence-transformers not available
+
+try:
+    if PyTorchEngine is not None:
+        EngineFactory.register(PyTorchEngine)
+except Exception:
+    pass  # torch or transformers not available
+
+__version__ = "0.2.2.6"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Configuration (for YAML/config files)
+    "BackendConfig",
+    "DemoConfig",
+    "EngineConfig",
+    "OutputConfig",
+    "WorkloadConfig",
+    "WorkloadSegment",
+    "load_config",
+    # Engine abstraction
+    "BaseEngine",
+    "EngineInstanceConfig",  # For runtime engine instantiation
+    "HealthStatus",
+    # Engine implementations
+    "CPUEngine",
+    "HFCudaEngine",
+    "HFCudaEngineConfig",
+    "EmbeddingEngine",
+    "EmbeddingEngineConfig",
+    "PyTorchEngine",
+    "PyTorchEngineConfig",
+    "PyTorchEngineInstanceConfig",
+    "create_pytorch_engine",
+    # Factory functions
+    "create_backend",
+    "create_engine",
+    "EngineFactory",
+    # Plugin system
+    "PluginResolutionError",
+    "list_entry_points",
+    "resolve_kind",
+    # Demo runner
+    "demo_main",
+    "DemoRunner",
+    "RunnerContext",
+]

sagellm_core/engines/__init__.py

@@ -0,0 +1,33 @@
+"""Engine implementations for sageLLM Core.
+
+This module provides built-in engine implementations:
+- CPUEngine: CPU-only inference with HuggingFace Transformers
+- HFCudaEngine: CUDA inference with HuggingFace Transformers
+- PyTorchEngine: Unified PyTorch engine (auto-detects CUDA/NPU/CPU)
+- EmbeddingEngine: Embedding model inference
+"""
+
+from __future__ import annotations
+
+from sagellm_core.engines.cpu import CPUEngine
+from sagellm_core.engines.embedding import EmbeddingEngine, EmbeddingEngineConfig
+from sagellm_core.engines.hf_cuda import HFCudaEngine, HFCudaEngineInstanceConfig
+from sagellm_core.engines.pytorch_engine import PyTorchEngine, create_pytorch_engine
+
+# Export aliases for backward compatibility
+HFCudaEngineConfig = HFCudaEngineInstanceConfig
+
+__all__ = [
+    # CPU engine
+    "CPUEngine",
+    # CUDA engine
+    "HFCudaEngine",
+    "HFCudaEngineConfig",
+    "HFCudaEngineInstanceConfig",
+    # PyTorch engine (unified)
+    "PyTorchEngine",
+    "create_pytorch_engine",
+    # Embedding engine
+    "EmbeddingEngine",
+    "EmbeddingEngineConfig",
+]

sagellm_core/py.typed

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