Metadata-Version: 2.4
Name: isagellm-backend
Version: 0.1.0
Summary: sageLLM backend provider abstraction and mock implementation
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: isagellm-protocol<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-mock>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: isagellm-core<0.2.0,>=0.1.0; extra == "dev"

# sagellm-backend

BackendProvider 抽象与内置 mock 实现。

- 仓库名：`sagellm-backend`
- PyPI 包名：`isagellm-backend`
- import 名：`sagellm_backend`

## 架构层级

```text
Level 0: sagellm-protocol (最基础，无依赖)
    ↓
Level 1: sagellm-backend (依赖 protocol) ← 当前包
    ↓
Level 2: sagellm-core (依赖 protocol + backend)
    ↓
Level 3: 功能模块（依赖 protocol + backend + core）
```

**依赖说明**：

- ✅ 生产依赖：`isagellm-protocol` (仅依赖 protocol)
- ✅ 开发依赖：`isagellm-core` (仅用于测试 entry point 机制)
- ❌ 不依赖：sagellm-core 的任何运行时功能

## Entry Points

- group：`sagellm.backends`
- 内置 kind：`mock`

其他硬件后端（ascend_cann/cuda 等）可通过独立插件包扩展，或在本仓库内添加 provider。

## 组件说明

### BackendProvider 抽象

- 定义统一的硬件抽象接口
- 覆盖：stream/event、集合通信、KV 块管理、kernel 注册
- 能力矩阵驱动（CapabilityDescriptor）

### Mock 实现

- 支持 CI 测试（无需真实硬件）
- 能力矩阵可配置（模拟不同后端能力）
- Fail-fast 错误处理

## 安装

```bash
pip install isagellm-backend
```

开发模式：

```bash
git clone https://github.com/intellistream/sagellm-backend.git
cd sagellm-backend
pip install -e ".[dev]"

# 安装 pre-commit hooks（强烈推荐）
pre-commit install
```

## 开发者指南

本项目使用完整的代码质量保障机制：

- ✅ **Pre-commit hooks**: 自动格式化和 lint
- ✅ **Unit tests**: 17 个单元测试 + 集成测试
- ✅ **CI/CD**: GitHub Actions 自动化测试
- ✅ **Type checking**: 100% 类型注解覆盖

详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 使用示例

```python
from sagellm_backend import MockBackendProvider, DType

# 创建 mock backend
backend = MockBackendProvider(
    supported_dtypes=[DType.FP16, DType.BF16],
    has_collective=True,
)

# 查询能力
cap = backend.capability()
print(cap.supported_dtypes)

# 分配 KV 块
block = backend.kv_block_alloc(128, DType.FP16)
```

## 扩展新后端

```python
# 在 providers/ 下创建新模块
class AscendBackendProvider:
    def capability(self) -> CapabilityDescriptor:
        return CapabilityDescriptor(
            supported_dtypes=[DType.FP16, DType.BF16, DType.INT8],
            # ...
        )

    # 实现其他接口...

# 注册 entry point (pyproject.toml)
[project.entry-points."sagellm.backends"]
ascend_cann = "sagellm_backend.providers.ascend:create_ascend_backend"
```
