isage 0.2.4.30

SAGE - Streaming-Augmented Generative Execution (meta package)

SAGE - Streaming-Augmented Generative Execution

A declarative, composable framework for building transparent LLM-powered systems through dataflow abstractions.

📚 Documentation Note: Links referencing docs-public/ point to the SAGE-Pub repository, which contains comprehensive documentation. Clone it separately if needed: git clone https://github.com/intellistream/SAGE-Pub.git

🚀 Quick Start

Try SAGE Studio

pip install isage-studio
sage-studio start

---

SAGE is a high-performance streaming framework for building AI-powered data processing pipelines. Transform complex LLM reasoning workflows into transparent, scalable, and maintainable systems through declarative dataflow abstractions.

Key Features

• Production-Ready: Distributed processing, fault tolerance, comprehensive monitoring
• Developer Experience: Complex AI pipelines in just a few lines of code
• High Performance: Optimized streaming with intelligent memory management
• Observable: Built-in visibility into execution and performance
• Flexible: CPU-only or GPU nodes with intelligent resource scheduling

Quick Start

Transform rigid LLM applications into flexible, observable workflows. Traditional imperative approaches create brittle systems:

# Traditional approach - rigid and hard to modify
def traditional_rag(query):
    docs = retriever.retrieve(query)
    if len(docs) < 3:
        docs = fallback_retriever.retrieve(query)
    prompt = build_prompt(query, docs)
    response = llm.generate(prompt)
    return response

SAGE transforms this into a declarative, composable workflow:

from sage.kernel.api.local_environment import LocalEnvironment
from sage.libs.foundation.io.source import FileSource
from sage.middleware.operators.llm import SageLLMGenerator  # ✅ Recommended
from sage.libs.foundation.io.sink import TerminalSink

# Create execution environment
env = LocalEnvironment("rag_pipeline")

# Build declarative pipeline with sageLLM (recommended)
(
    env.from_source(FileSource, {"data_path": "questions.txt"})
    .map(SageLLMGenerator, {
        "model_path": "Qwen/Qwen2.5-7B-Instruct",
        "backend_type": "auto",  # auto/cuda/ascend/mock
    })
    .sink(TerminalSink)
)

# Execute pipeline
env.submit()

💡 LLM Engine: SAGE uses sageLLM as the default inference engine. For OpenAI-compatible APIs, use OpenAIGenerator. See CHANGELOG for legacy migration notes.

Current API quick reference

• sage.libs.foundation.io.source: FileSource, TextFileSource, CSVFileSource, JSONFileSource
• sage.libs.foundation.io.sink: TerminalSink, FileSink
• sage.middleware.operators.rag: RAGDocument, RAGQuery, RAGResponse
• sage.middleware.operators.llm: SageLLMGenerator

Try it yourself:

git clone https://github.com/intellistream/SAGE.git && cd SAGE
git checkout main-dev
./quickstart.sh --dev --yes

# Tutorials are now in a separate repository
git clone https://github.com/intellistream/sage-tutorials.git
python sage-tutorials/L1-common/hello_world.py

For CPU-only deployment:

# Start JobManager for distributed task execution
sage jobmanager start

# Run CPU node demo (no GPU required)
git clone https://github.com/intellistream/sage-tutorials.git
python sage-tutorials/L3-kernel/cpu_node_demo.py

Architecture

SAGE has a 5-layer core architecture (L1-L5) with each core layer independently released as its own package:

L5: sage-cli                          # CLI & Dev Tools       (isage-cli)
L4: sage-middleware                   # Operators / C++ ext   (isage-middleware)
L3: sage-kernel, sage-libs            # Runtime & algorithms  (isage-kernel, isage-libs)
L2: sage-platform                     # Queue, storage        (isage-platform)
L1: sage-common                       # Foundation            (isage-common)

Above the core stack, ecosystem repositories (applications, benchmarks, docs, websites) are classified as L6.

See SAGE Ecosystem for all independent sub-repositories with CI status, PyPI packages, and categorized listings.

📖 Architecture Guide - Detailed design principles and dependency rules

📌 Layer Ownership Matrix v1 (Wave A) - Canonical L1-L5 ownership, independent sub-repo coordination boundary (including sagellm capabilities), forbidden directions, and boundary refactor review checklist

Installation

Quickstart (Recommended)

git clone https://github.com/intellistream/SAGE.git && cd SAGE
./quickstart.sh --dev --yes         # 开发模式：尽量本地 editable
# 或
./quickstart.sh --standard --yes    # 标准模式：子包依赖默认从 PyPI 安装

⚡ Auto-Acceleration: Network optimization is now enabled by default:

• 🌐 Auto-detects network location (China mainland → mirror sources)
• 🚀 Parallel downloads (8 threads) + pre-compiled packages
• ⏱️ 3-5x faster installation: 12-18 min (vs 35-45 min)
• 🔧 Disable: ./quickstart.sh --no-mirror --dev --yes

Install Mode Semantics

• standard：本地安装 packages/sage，子包依赖按 packages/sage/pyproject.toml 版本从 PyPI 解析。
• dev：先完成 standard 安装，再尽量将同级工作区中的本地 SAGE 子仓库切换为 editable (-e)。

PyPI Install

pip install isage              # Core framework
pip install isage[dev]         # Development tools (includes pre-commit, pytest, etc.)

What's included in pip install isage

isage is a meta-package that bundles the full framework stack: isage-common (L1) · isage-platform (L2) · isage-kernel + isage-libs (L3) · isage-middleware (L4) · isage-cli (L5) · isage-flow (runtime) · isagellm (LLM gateway)

Capability Packages (bundled with isage) 🧩

For a standard pip install isage, these packages are installed transitively and do not require extra manual installation:

Feature	Included Package	Notes
Agents	isage-agentic	ReAct, PlanExecute, complex reasoning
Vector DB	isage-vdb	Fast vector search (SageVDB)
Memory Systems	isage-neuromem	Persistent memory + sessions
Privacy	isage-privacy	Differential privacy, PII handling
LLM Gateway	isagellm	Control plane, unified inference client

Optional packages (not bundled — install separately) 🦁

These packages were moved to independent repositories and are no longer part of the default isage install. See SAGE Zoo guide for the full list with one-liner descriptions and install commands.

pip install isage-rag              # RAG 管道（文档加载 / 分块 / 检索 / 重排）
pip install isage-eval             # 评估框架（指标 / LLM 评判）
pip install isage-finetune         # LLM 微调（LoRA / 数据加载器）
pip install isage-agentic-tooluse  # Agent 工具选择（Hybrid/DFS/Gorilla）
pip install isage-intent           # 意图识别（关键词 + LLM）

Example: install full core SAGE stack

pip install isage

See Dependency Management in DEVELOPER.md for detailed guidance.

Verification & Troubleshooting

sage doctor                    # Check installation
./quickstart.sh --doctor       # Diagnose issues

📖 Detailed guides: Installation Guide | Troubleshooting | Validation | Optimization Tips

⚠️ Known Issues: If you encounter transformers version conflicts when installing multiple SAGE packages, see Dependency Fix Guide

Environment Configuration

cp .env.template .env    # Copy template
# Edit .env and add your API keys (OPENAI_API_KEY, HF_TOKEN, etc.)

📖 API key setup: See .env.template for all available options

📚 Tutorials

Complete tutorials covering all layers of SAGE (L1-L5):

# Clone tutorials repository
git clone https://github.com/intellistream/sage-tutorials.git
cd sage-tutorials

# Start learning (30 seconds)
python L1-common/hello_world.py

# Follow the quick start guide
cat QUICK_START.md

Tutorial Structure:

• sage-tutorials/L1-common/ - Foundation layer (config, logging, unified client)
• sage-tutorials/L2-platform/ - Platform services (scheduler, storage)
• sage-tutorials/L3-kernel/ - Execution engine (batch, stream, operators)
• sage-tutorials/L3-libs/ - RAG, Agents, Algorithms
• sage-tutorials/L4-middleware/ - Domain operators (vector DB, time-series)
• sage-tutorials/L5-apps/ - Applications and integration demos

See sage-tutorials/README.md for complete learning paths.

Documentation & Resources

• Documentation: https://intellistream.github.io/SAGE-Pub/
• Examples & Applications: intellistream/sage-examples
  • RAG examples and production applications
  • Will be published as isage-examples on PyPI
• Tutorials: intellistream/sage-tutorials
  • Layered tutorials from L1 to L5, quick-start learning paths
• Architecture: docs-public/docs_src/concepts/architecture/package-structure.md

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git checkout -b feature/my-feature
./quickstart.sh --dev --yes
# Make changes, add tests
sage-dev quality && sage-dev test
git commit -m "feat(kernel): add new feature"
git push -u origin feature/my-feature

Resources: Quick Reference | GitHub Issues | Discussions

Team Information

🔒 Team assignments and sensitive information are maintained in a private repository to protect member privacy.

• Public: Project-level information is available in this repository
• Private: Team member assignments, funding details, and contact information are accessible to authorized members only
• Access: Contact project management for access to the private repository

Developer Tools

make help           # View all commands
sage-dev quality    # Format & lint
sage-dev test       # Run tests
make docs           # Build documentation

📖 Complete reference: DEVELOPER.md

SAGE Ecosystem

📦 SAGE Zoo guide — 独立可选包（已 zoo 化，各自独立演进）

🧠 SAGE — Streaming AI Framework

SAGE is a streaming AI framework decomposed into 5 independently-released layer packages:

Core Layers

• sage-common (L1) — Foundation utilities, config, logging
• sage-platform (L2) — Queue, storage, and service abstractions
• sage-kernel (L3) — Streaming runtime, scheduler, flow DSL
• sage-libs (L3) — Algorithm library (RAG, agents, ANNS interfaces)
• sage-middleware (L4) — Domain operators with C++ extensions
• sage-cli (L5) — Unified CLI and developer tooling

Independent sub-repositories are organized by category:

Application & UI

• sage-studio — Visual workflow builder and LLM playground
• sage-examples — Tutorials and application examples

Algorithms & Libraries

• sage-agentic — ReAct, PlanExecute agents and agentic workflows
• sage-rag — Retrieval-augmented generation components
• sageVDB — High-performance vector database (FAISS-compatible API)
• sageRefiner — Query and response refinement algorithms
• sage-amms — Approximate matrix multiplication service
• sageFlownet — Streaming flownet execution engine 🔒 private

Data & Benchmarks

• sageData — Unified dataset management for SAGE subsystems
• sage-benchmark — Comprehensive evaluation framework for RAG, agents, memory, and control plane
• sage-eval — Evaluation metrics, profilers, and LLM judges

Model Optimization & Safety

• sage-finetune — Model fine-tuning and adaptation
• sage-privacy — Differential privacy and PII handling
• sage-safety — Safety filters and guardrails

Developer Tooling

• sage-dev-tools — Development CLI and quality tooling
• sage-kernel — Extracted kernel modules (public)

---

⚡ sageLLM — LLM Inference Engine

sageLLM is a modular, high-performance LLM inference engine. All repositories are 🔒 private and published to PyPI.

Core Engine

• sagellm-core — Core inference engine
• sagellm-backend — Backend drivers (CUDA, Ascend)
• sagellm-protocol — Wire protocol and serialization

Gateway & Control

• sagellm-gateway — OpenAI-compatible API gateway
• sagellm-control-plane — Scheduling and resource management

Optimization

• sagellm-kv-cache — KV cache management
• sagellm-comm — Communication layer
• sagellm-compression — Compression algorithms

Tooling & Benchmarks

• sagellm-benchmark — Performance benchmarks
• sagellm-dev-tools — Development tooling

Community

💬 Join SAGE Community - WeChat, QQ, Slack, GitHub Discussions

License

SAGE is licensed under the MIT License.