Metadata-Version: 2.4
Name: isage-middleware
Version: 0.1.1
Summary: SAGE Middleware Module
Author-email: IntelliStream Team <intellistream@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/intellistream/SAGE
Project-URL: Repository, https://github.com/intellistream/SAGE.git
Project-URL: Documentation, https://intellistream.github.io/SAGE-Pub/
Project-URL: Issues, https://github.com/intellistream/SAGE/issues
Keywords: data,api,reasoning,dataflow,llm,ml,middleware,framework,rag,intellistream,ai,sage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: isage-kernel>=0.1.0
Requires-Dist: python-jose==3.5.0
Requires-Dist: passlib==1.7.4
Requires-Dist: ascii_colors>=0.11.4
Requires-Dist: pipmaster>=0.9.2
Requires-Dist: tenacity==9.1.2
Requires-Dist: celery==5.5.3
Requires-Dist: flower==2.0.1
Requires-Dist: openai<=1.90.0,>=1.52.0
Requires-Dist: ollama==0.5.1
Requires-Dist: zhipuai==2.1.5.20250801
Requires-Dist: cohere==5.16.1
Requires-Dist: transformers>=4.54.1
Requires-Dist: tokenizers==0.21.4
Requires-Dist: faiss-cpu==1.9.0
Requires-Dist: bm25s==0.2.13
Requires-Dist: rank-bm25==0.2.2
Requires-Dist: PyStemmer==3.0.0
Requires-Dist: aiohttp==3.12.15
Requires-Dist: frozenlist==1.7.0
Requires-Dist: httpx==0.28.1
Requires-Dist: certifi==2025.8.3
Requires-Dist: feedparser==6.0.11
Requires-Dist: accelerate==1.9.0
Requires-Dist: sentence-transformers==3.1.1
Requires-Dist: InstructorEmbedding==1.0.1
Requires-Dist: huggingface-hub==0.34.3
Requires-Dist: peft==0.17.0
Requires-Dist: numpy<3.0.0,>=1.25.0
Requires-Dist: scipy==1.15.3
Requires-Dist: fastapi==0.115.12
Requires-Dist: uvicorn==0.34.3
Requires-Dist: pydantic
Requires-Dist: pyyaml==6.0.2
Provides-Extra: sage
Requires-Dist: isage-common>=0.1.0; extra == "sage"
Provides-Extra: enterprise
Requires-Dist: isage-middleware[sage]; extra == "enterprise"
Requires-Dist: sqlalchemy>=2.0.0; extra == "enterprise"
Requires-Dist: alembic>=1.13.0; extra == "enterprise"
Requires-Dist: asyncpg>=0.30.0; extra == "enterprise"
Requires-Dist: pymongo[srv]>=4.8.0; extra == "enterprise"
Requires-Dist: redis>=5.2.0; extra == "enterprise"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "enterprise"
Requires-Dist: cx-Oracle>=8.3.0; extra == "enterprise"
Requires-Dist: pyodbc>=4.0.0; extra == "enterprise"
Requires-Dist: pymysql>=1.1.0; extra == "enterprise"
Requires-Dist: celery>=5.5.0; extra == "enterprise"
Requires-Dist: kafka-python>=2.0.0; extra == "enterprise"
Requires-Dist: apache-airflow>=2.8.0; extra == "enterprise"
Requires-Dist: orjson>=3.8.0; extra == "enterprise"
Requires-Dist: msgpack>=1.0.0; extra == "enterprise"
Requires-Dist: pyarrow>=15.0.0; extra == "enterprise"
Requires-Dist: python-memcached>=1.6.0; extra == "enterprise"
Requires-Dist: elasticsearch>=8.0.0; extra == "enterprise"
Requires-Dist: prometheus-client>=0.19.0; extra == "enterprise"
Requires-Dist: jaeger-client>=4.8.0; extra == "enterprise"
Provides-Extra: enterprise-dev
Requires-Dist: isage-middleware[enterprise]; extra == "enterprise-dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "enterprise-dev"
Requires-Dist: pytest-docker>=2.0.0; extra == "enterprise-dev"
Requires-Dist: testcontainers>=3.7.0; extra == "enterprise-dev"
Provides-Extra: vllm
Requires-Dist: vllm<0.7.0,>=0.6.0; extra == "vllm"
Provides-Extra: database
Requires-Dist: sqlalchemy==2.0.32; extra == "database"
Requires-Dist: alembic==1.13.2; extra == "database"
Requires-Dist: asyncpg==0.30.0; extra == "database"
Requires-Dist: pymongo[srv]==4.8.0; extra == "database"
Provides-Extra: messagequeue
Requires-Dist: celery==5.5.3; extra == "messagequeue"
Requires-Dist: redis==5.2.1; extra == "messagequeue"
Requires-Dist: kafka-python==2.0.3; extra == "messagequeue"
Requires-Dist: pika==1.3.2; extra == "messagequeue"
Provides-Extra: monitoring
Requires-Dist: prometheus-client==0.21.1; extra == "monitoring"
Requires-Dist: structlog==24.4.0; extra == "monitoring"
Requires-Dist: sentry-sdk[fastapi]==2.18.0; extra == "monitoring"
Provides-Extra: llm
Requires-Dist: anthropic==0.34.2; extra == "llm"
Requires-Dist: google-generativeai==0.8.3; extra == "llm"
Requires-Dist: cohere==5.16.2; extra == "llm"
Requires-Dist: langchain==0.3.18; extra == "llm"
Requires-Dist: llama-index==0.11.33; extra == "llm"
Provides-Extra: full
Requires-Dist: sage-middleware[database,llm,messagequeue,monitoring,websocket]; extra == "full"
Provides-Extra: testing
Requires-Dist: isage-middleware[sage]; extra == "testing"
Requires-Dist: pytest==8.3.4; extra == "testing"
Requires-Dist: pytest-asyncio==0.25.0; extra == "testing"
Requires-Dist: pytest-cov==6.0.0; extra == "testing"
Requires-Dist: pytest-benchmark==4.0.0; extra == "testing"
Requires-Dist: testcontainers==4.8.2; extra == "testing"
Requires-Dist: pytest-mock==3.14.0; extra == "testing"


# SAGE 微服务架构改造

## 📋 改造概述

本次改造将SAGE的集成式memory service重构为真正的服务化架构，符合您提出的要求：

1. ✅ **使用sage-kernel的BaseServiceTask** - 所有服务继承自`sage.kernels.runtime.service.base_service_task.BaseServiceTask`
2. ✅ **服务作为Task运行** - 服务本质上是特殊的Task，可以在DAG中作为节点运行
3. ✅ **移除服务启动脚本** - 不再有独立的服务启动器，服务由应用程序在构建DAG时初始化
4. ✅ **支持Ray分布式** - 服务可以作为Ray Actor运行，支持集群部署

## 🏗️ 新架构

```
用户应用
    ↓ 注册服务
SAGE Environment
    ↓ 创建DAG
Service Tasks (BaseServiceTask)
    ├── KVService (键值存储)
    ├── VDBService (向量数据库) 
    └── MemoryOrchestratorService (记忆编排)
        ↓ 队列通信
    其他Function Tasks
```

## 🔧 核心组件

### 1. KVService
- **文件**: `src/sage/service/kv/kv_service.py`
- **基类**: `BaseServiceTask`
- **后端**: 内存 或 Redis
- **方法**: `get()`, `put()`, `delete()`, `list_keys()`, `clear()`

### 2. VDBService  
- **文件**: `src/sage/service/vdb/vdb_service.py`
- **基类**: `BaseServiceTask`
- **后端**: ChromaDB
- **方法**: `add()`, `search()`, `get()`, `delete()`, `update()`

### 3. MemoryOrchestratorService
- **文件**: `src/sage/service/memory_orchestrator/memory_service.py`
- **基类**: `BaseServiceTask`
- **功能**: 协调KV和VDB服务，提供统一记忆管理
- **方法**: `store_memory()`, `search_memories()`, `get_memory()`

## 🚀 使用方式

### 第一步：注册服务

```python
from sage.api.local_environment import LocalEnvironment
from sage.middleware.services import (
    create_kv_service_factory,
    create_vdb_service_factory,
    create_memory_service_factory
)

# 创建环境
env = LocalEnvironment("my_app", {})

# 注册服务
env.register_service("kv_service", KVService, create_kv_service_factory())
env.register_service("vdb_service", VDBService, create_vdb_service_factory()) 
env.register_service("memory_service", MemoryOrchestratorService, create_memory_service_factory())
```

### 第二步：在Function中使用

```python
from sage.api.function.base_function import BaseFunction

class MyProcessor(BaseFunction):
    def process(self, data):
        # 直接调用服务
        self.call_service["kv_service"].put("key1", data)
        result = self.call_service["memory_service"].store_memory(
            session_id="session_1",
            content=data['content'],
            vector=data['vector']
        )
        return result
```

### 第三步：构建DAG并运行

```python
# 创建数据流
stream = env.from_kafka_source(...)

# 应用处理函数
processed = stream.map(MyProcessor())

# 运行（服务自动启动）
env.execute()
```

## 📁 项目结构

```
packages/sage-middleware/
├── src/sage/service/
│   ├── __init__.py                     # 统一接口
│   ├── kv/kv_service.py               # KV服务任务
│   ├── vdb/vdb_service.py             # VDB服务任务
│   ├── memory_orchestrator/memory_service.py  # Memory编排服务
│   └── memory/                        # 旧版服务(兼容)
├── examples/
│   ├── dag_microservices_demo.py      # 完整使用演示
│   └── run_demo.sh                    # 快速启动脚本
├── MICROSERVICES_GUIDE.md             # 详细使用指南
└── README.md                          # 本文件
```

## 🎯 关键特性

### 1. 真正的服务化
- 每个服务都是独立的BaseServiceTask
- 服务可以单独运行、测试和扩展
- 支持不同的技术栈和存储后端

### 2. DAG集成
- 服务作为Task节点在DAG中运行
- 与其他数据处理Task无缝集成
- 统一的生命周期管理

### 3. 队列通信
- 使用SAGE的高性能队列机制
- 支持同步和异步调用
- 自动请求/响应匹配

### 4. 分布式支持
- 服务可以作为Ray Actor运行
- 支持跨节点服务调用
- 自动负载均衡和故障恢复

### 5. 应用控制
- 应用程序控制服务的启动和配置
- 不需要外部服务管理器
- 灵活的服务组合和依赖关系

## 📊 性能优势

1. **高效通信**: 队列机制比HTTP调用更高效
2. **内存优化**: 服务和数据处理共享内存空间
3. **批处理**: 支持批量服务调用
4. **并发处理**: 服务可以并发处理多个请求

## 🔄 迁移路径

### 从HTTP微服务迁移
- 移除HTTP客户端代码
- 使用`self.call_service[service_name].method()`替代HTTP调用
- 服务注册到SAGE环境而不是独立启动

### 从集成式服务迁移  
- 将大型服务拆分为独立的Service Task
- 使用服务调用替代直接方法调用
- 保持相同的业务逻辑和API

## 🧪 运行演示

```bash
# 快速启动
cd packages/sage-middleware
./examples/run_demo.sh

# 或直接运行Python
python examples/dag_microservices_demo.py
```

## 📚 参考文档

- **微服务指南**: [MICROSERVICES_GUIDE.md](MICROSERVICES_GUIDE.md)
- **SAGE文档**: [packages/sage-kernel/src/sage/runtime/service/README.md](../sage-kernel/src/sage/runtime/service/README.md)
- **BaseServiceTask**: [packages/sage-kernel/src/sage/runtime/service/base_service_task.py](../sage-kernel/src/sage/runtime/service/base_service_task.py)

---

## ✅ 改造成果

这次改造成功实现了您要求的所有目标：

1. ✅ **继承sage-kernel的BaseServiceTask** - 所有服务都继承正确的基类
2. ✅ **服务即Task** - 服务本质上是在DAG中运行的特殊Task
3. ✅ **应用控制** - 用户在构建DAG时初始化服务，而非独立启动脚本
4. ✅ **支持Ray** - 服务可以作为Ray Actor分布式运行
5. ✅ **队列通信** - 使用SAGE统一的高性能队列机制
6. ✅ **向后兼容** - 保留原有API兼容性

现在SAGE拥有了真正的服务化架构，每个服务都是独立的Task，可以灵活组合、分布式部署，完全符合现代微服务架构的设计理念！
=======
# SAGE Middleware - 中间件组件

SAGE Middleware提供中间件服务，包含LLM中间件、API服务、任务队列等企业级功能。

## 主要功能

### LLM中间件服务
- **多模型支持**: OpenAI、Ollama、智谱AI、Cohere等
- **统一API**: 标准化的LLM调用接口
- **高性能推理**: 基于vLLM的优化推理服务
- **模型管理**: 动态模型加载和卸载

### API服务
- **RESTful API**: 基于FastAPI的高性能API服务
- **认证授权**: JWT令牌和密码加密支持
- **服务发现**: 自动服务注册和发现

### 任务队列
- **异步处理**: 基于Celery的分布式任务队列
- **监控界面**: Flower监控和管理界面
- **容错机制**: 任务重试和错误处理

### 向量检索
- **FAISS集成**: 高性能向量相似度搜索
- **BM25搜索**: 传统文本检索算法
- **混合检索**: 向量和关键词混合检索

## 安装

```bash
pip install intellistream-sage-middleware
```

## 基本使用

### 启动LLM服务

```python
from sage.middleware.llm import LLMService

# 创建LLM服务
service = LLMService()

# 注册模型
service.register_model("gpt-3.5-turbo", provider="openai")
service.register_model("llama2", provider="ollama")

# 启动服务
service.start()
```

### API调用

```python
import requests

# 文本生成
response = requests.post("http://localhost:8000/generate", json={
    "model": "gpt-3.5-turbo",
    "prompt": "Hello, how are you?",
    "max_tokens": 100
})

result = response.json()
print(result["text"])
```

### 向量检索

```python
from sage.middleware.retrieval import VectorStore

# 创建向量存储
store = VectorStore()

# 添加文档
store.add_documents([
    "This is document 1",
    "This is document 2"
])

# 搜索
results = store.search("document", top_k=5)
for result in results:
    print(f"Score: {result.score}, Text: {result.text}")
```

## 配置

中间件服务可以通过环境变量或配置文件进行配置：

```yaml
# config.yaml
llm:
  providers:
    openai:
      api_key: "your-api-key"
    ollama:
      base_url: "http://localhost:11434"

api:
  host: "0.0.0.0"
  port: 8000
  
queue:
  broker: "redis://localhost:6379"
  backend: "redis://localhost:6379"
```

## 许可证

MIT License
