isagellm 0.1.0.6

sageLLM: Modular LLM inference engine for domestic computing power (Huawei Ascend, NVIDIA)

sageLLM

🚀 Modular LLM Inference Engine for Domestic Computing Power

Ollama-like experience for Chinese hardware ecosystems (Huawei Ascend, NVIDIA)

---

✨ Features

• 🎯 One-Click Install - pip install isagellm gets you started immediately
• 🔌 Mock-First - Test without GPU, perfect for CI/CD
• 🇨🇳 Domestic Hardware - First-class support for Huawei Ascend NPU
• 📊 Observable - Built-in metrics (TTFT, TBT, throughput, KV usage)
• 🧩 Plugin System - Extend with custom backends and engines

📦 Quick Install

# Install sageLLM (includes mock backend, no GPU required)
pip install isagellm

# With Control Plane (request routing & scheduling)
pip install 'isagellm[control-plane]'

# With API Gateway (OpenAI-compatible REST API)
pip install 'isagellm[gateway]'

# Full server (Control Plane + Gateway)
pip install 'isagellm[server]'

# With CUDA support
pip install 'isagellm[cuda]'

# All features
pip install 'isagellm[all]'

🚀 Quick Start

启动模式选择

sageLLM 支持两种启动模式，满足不同场景需求：

模式	使用场景	依赖	命令示例
Mock	CI/测试/本地开发	无需 GPU	sage-llm serve --mock
生产	真实推理服务	GPU/CPU 后端	sage-llm serve --control-plane

⚠️ Fail-Fast 保证：非 mock 模式下，若依赖缺失或配置错误，系统将立即报错退出，不会静默回退到 mock 模式。

CLI (like ollama)

# Show system info
sage-llm info

# Mock 模式（无 GPU 依赖）
sage-llm serve --mock
sage-llm run -p "What is LLM inference?" --mock
sage-llm demo --workload year1 --mock

# 生产模式（需要安装 control-plane）
# pip install 'isagellm[server]'
sage-llm serve --control-plane
sage-llm gateway --control-plane --port 8080

# 如果缺少依赖，将看到：
# ❌ Error: Control Plane required but not installed
#    Install: pip install 'isagellm[control-plane]'

Python API

from sagellm import Request, MockEngine

# Create mock engine (no GPU needed)
engine = MockEngine()

# Run inference
request = Request(
    request_id="demo-001",
    prompt="Hello, world!",
    max_tokens=128,
)
response = engine.generate(request)

print(f"Response: {response.text}")
print(f"TTFT: {response.metrics.ttft_ms:.2f} ms")
print(f"Throughput: {response.metrics.throughput_tps:.2f} tokens/s")

Configuration

# ~/.sage-llm/config.yaml
backend:
  kind: mock  # Options: mock, cpu, cuda, ascend
  
  # Fail-fast 配置：如果指定了非 mock 后端但不可用，将报错退出
  strict_mode: true  # 默认为 true，符合申报书要求

engine:
  kind: mock
  model: Qwen/Qwen2-7B

# Mock 模式配置
mock:
  enabled: false      # true 时强制使用 mock，无论其他配置
  deterministic: true # mock 输出是否固定（用于回归测试）

# 生产模式最低要求
production:
  control_plane:
    required: true    # true 时缺少 control-plane 将报错（非 mock 模式）
    endpoint: "localhost:8080"
  backend:
    required: true    # true 时缺少真实后端将报错
    fallback_to_mock: false  # 禁止自动降级到 mock（fail-fast）

workload:
  segments:
    - short   # 128 in → 128 out
    - long    # 2048 in → 512 out
    - stress  # concurrent requests

📊 Year 1 Demo Contract

sageLLM must produce these metrics for validation:

{
  "ttft_ms": 45.2,
  "tbt_ms": 12.5,
  "throughput_tps": 80.0,
  "peak_mem_mb": 24576,
  "kv_used_tokens": 4096,
  "prefix_hit_rate": 0.85,
  "evict_count": 3
}

Run validation:

sage-llm demo --workload year1 --output metrics.json

🏗️ Architecture

isagellm (umbrella package)
├── isagellm-protocol       # Protocol v0.1 types
│   └── Request, Response, Metrics, Error, StreamEvent
├── isagellm-core           # Runtime & Demo Runner
│   └── Config, Engine, Factory, DemoRunner
├── isagellm-backend        # Hardware abstraction
│   └── BackendProvider, MockBackend, (CUDABackend, AscendBackend)
├── isagellm-control-plane  # Request routing & scheduling (optional)
│   └── ControlPlaneManager, Router, Policies, Lifecycle
└── isagellm-gateway        # OpenAI-compatible REST API (optional)
    └── FastAPI server, /v1/chat/completions, Session management

🔧 Development

Quick Setup (Development Mode)

# Clone all repositories
./scripts/clone-all-repos.sh

# Install all packages in editable mode
./quickstart.sh

# Open all repos in VS Code Multi-root Workspace
code sagellm.code-workspace

📖 See WORKSPACE_GUIDE.md for Multi-root Workspace usage.

Testing

# Clone and setup
git clone https://github.com/IntelliStream/sagellm.git
cd sagellm
pip install -e ".[dev]"

# Run tests
pytest -v

# Format & lint
ruff format .
ruff check . --fix

# Type check
mypy src/sagellm/

# Verify dependency hierarchy
python scripts/verify_dependencies.py

📖 Development Resources

• DEPLOYMENT_GUIDE.md - 完整部署与配置指南
• TROUBLESHOOTING.md - 故障排查快速参考
• ENVIRONMENT_VARIABLES.md - 环境变量完整参考
• DEVELOPER_GUIDE.md - 开发者指南
• WORKSPACE_GUIDE.md - Multi-root Workspace 使用
• INFERENCE_FLOW.md - 推理流程详解
• PR_CHECKLIST.md - Pull Request 检查清单

---

📚 Documentation Index

用户文档

• 快速开始 - 5 分钟上手
• 部署指南 - 生产环境部署
• 配置参考 - 完整配置选项
• 环境变量 - 环境变量参考
• 故障排查 - 常见问题解决

开发者文档

• 开发指南 - 贡献代码
• 架构设计 - 系统架构
• Workspace 使用 - Multi-root 工作区
• PR 检查清单 - 提交前检查

API 文档

• OpenAI 兼容 API - 参见 sagellm-gateway
• Python API - 参见 API_REFERENCE.md（待补充）

子包文档

• sagellm-protocol - 协议定义

• sagellm-backend - 后端抽象

• sagellm-core - 引擎核心

• sagellm-control-plane - 控制面

• sagellm-gateway - API 网关

• sagellm-benchmark - 基准测试

• DEVELOPER_GUIDE.md - 架构规范与开发指南

• PR_CHECKLIST.md - Pull Request 审查清单

• scripts/verify_dependencies.py - 依赖层次验证

📚 Package Details

Package	PyPI Name	Import Name	Description
sagellm	isagellm	sagellm	Umbrella package (install this)
sagellm-protocol	isagellm-protocol	sagellm_protocol	Protocol v0.1 types
sagellm-core	isagellm-core	sagellm_core	Runtime & config
sagellm-backend	isagellm-backend	sagellm_backend	Hardware abstraction

🎯 Roadmap

• Year 1: Core inference with KV cache, prefix sharing, basic eviction
• Year 2: Multi-node inference, advanced scheduling
• Year 3: Full production-ready deployment

📄 License

Proprietary - IntelliStream. Internal use only.

---

_{Built with ❤️ by IntelliStream Team for domestic AI infrastructure}