isage-middleware 0.1.4__py3-none-any.whl → 0.1.5.1__py3-none-any.whl

sage/middleware/examples/api_usage_tutorial.py

@@ -1,339 +0,0 @@
-"""
-SAGE Services API Usage Tutorial
-展示如何正确使用SAGE微服务的API接口
-"""
-import asyncio
-import numpy as np
-from typing import List, Dict, Any
-
-# 导入API接口
-from sage.middleware.api import KVServiceAPI, VDBServiceAPI, MemoryServiceAPI, GraphServiceAPI
-
-# 导入具体服务实现和工厂函数
-from sage.middleware.services import (
-    KVService, VDBService, MemoryService, GraphService,
-    create_kv_service_factory, create_vdb_service_factory,
-    create_memory_service_factory, create_graph_service_factory,
-)
-from sage.core.api.local_environment import LocalEnvironment
-
-
-class ServiceAPITutorial:
-    """SAGE服务API使用教程"""
-    
-    def __init__(self):
-        self.env = LocalEnvironment("api_tutorial_demo")
-        self.setup_services()
-    
-    def setup_services(self):
-        """设置所有服务"""
-        print("🚀 Setting up SAGE Services for API Tutorial")
-        print("=" * 60)
-        
-        # 注册KV服务
-        kv_factory = create_kv_service_factory(
-            service_name="tutorial_kv",
-            backend_type="memory",
-            max_size=10000
-        )
-        self.env.register_service_factory("tutorial_kv", kv_factory)
-        
-        # 注册VDB服务
-        vdb_factory = create_vdb_service_factory(
-            service_name="tutorial_vdb",
-            embedding_dimension=384,
-            max_vectors=10000
-        )
-        self.env.register_service_factory("tutorial_vdb", vdb_factory)
-        
-        # 注册Memory服务
-        memory_factory = create_memory_service_factory(
-            service_name="tutorial_memory",
-            kv_service_name="tutorial_kv",
-            vdb_service_name="tutorial_vdb"
-        )
-        self.env.register_service_factory("tutorial_memory", memory_factory)
-        
-        print("✅ All services registered successfully")
-    
-    def demonstrate_kv_api(self):
-        """演示KV API的正确使用方式"""
-        print("\n📦 KV Service API Tutorial")
-        print("-" * 40)
-        
-        # 在实际应用中，你会从环境中获取服务代理
-        # 这里我们模拟API调用的预期行为
-        
-        print("💡 KV Service API Interface:")
-        print("   - put(key, value) -> bool")
-        print("   - get(key) -> Any")
-        print("   - delete(key) -> bool")
-        print("   - exists(key) -> bool")
-        print("   - list_keys(prefix) -> List[str]")
-        print("   - size() -> int")
-        print("   - clear() -> bool")
-        
-        print("\n📝 Expected Usage Pattern:")
-        usage_example = '''
-# 获取KV服务代理
-kv_service = env.get_service_proxy("tutorial_kv")
-
-# 基本操作
-success = kv_service.put("user:123", {"name": "Alice", "age": 30})
-user_data = kv_service.get("user:123")
-exists = kv_service.exists("user:123")
-
-# 批量操作
-keys = kv_service.list_keys("user:")
-total_size = kv_service.size()
-
-# 删除操作
-deleted = kv_service.delete("user:123")
-'''
-        print(usage_example)
-        
-        # 模拟执行结果
-        print("🎯 Expected Results:")
-        print("   put() -> True")
-        print("   get() -> {'name': 'Alice', 'age': 30}")
-        print("   exists() -> True")
-        print("   list_keys('user:') -> ['user:123']")
-        print("   size() -> 1")
-        print("   delete() -> True")
-    
-    def demonstrate_vdb_api(self):
-        """演示VDB API的正确使用方式"""
-        print("\n🗂️ VDB Service API Tutorial")
-        print("-" * 40)
-        
-        print("💡 VDB Service API Interface:")
-        print("   - add_vectors(documents) -> List[str]")
-        print("   - search(query_vector, top_k, threshold) -> List[Dict]")
-        print("   - get_vector(doc_id) -> Dict")
-        print("   - delete_vectors(doc_ids) -> bool")
-        print("   - update_vector(doc_id, document) -> bool")
-        print("   - count() -> int")
-        print("   - save_index(path) -> bool")
-        print("   - load_index(path) -> bool")
-        
-        print("\n📝 Expected Usage Pattern:")
-        usage_example = '''
-# 获取VDB服务代理
-vdb_service = env.get_service_proxy("tutorial_vdb")
-
-# 添加向量文档
-documents = [{
-    "id": "doc_001",
-    "vector": [0.1, 0.2, 0.3, ...],  # 384维向量
-    "text": "这是一个示例文档",
-    "metadata": {"category": "example"}
-}]
-doc_ids = vdb_service.add_vectors(documents)
-
-# 向量搜索
-query_vector = [0.1, 0.2, 0.3, ...]  # 查询向量
-results = vdb_service.search(
-    query_vector=query_vector,
-    top_k=5,
-    similarity_threshold=0.8
-)
-
-# 获取特定文档
-document = vdb_service.get_vector("doc_001")
-
-# 更新和删除
-updated = vdb_service.update_vector("doc_001", new_document)
-deleted = vdb_service.delete_vectors(["doc_001"])
-'''
-        print(usage_example)
-        
-        print("🎯 Expected Results:")
-        print("   add_vectors() -> ['doc_001']")
-        print("   search() -> [{'id': 'doc_001', 'score': 0.95, ...}]")
-        print("   get_vector() -> {'id': 'doc_001', 'vector': [...], ...}")
-        print("   count() -> 1")
-    
-    def demonstrate_memory_api(self):
-        """演示Memory API的正确使用方式"""
-        print("\n🧠 Memory Service API Tutorial")
-        print("-" * 40)
-        
-        print("💡 Memory Service API Interface (High-level):")
-        print("   - store_memory(content, vector, session_id, ...) -> str")
-        print("   - retrieve_memories(query_vector, session_id, ...) -> List[Dict]")
-        print("   - get_memory(memory_id) -> Dict")
-        print("   - delete_memory(memory_id) -> bool")
-        print("   - search_memories(query, session_id, ...) -> List[Dict]")
-        print("   - get_session_memories(session_id) -> List[Dict]")
-        print("   - clear_session_memories(session_id) -> bool")
-        
-        print("\n📝 Expected Usage Pattern:")
-        usage_example = '''
-# 获取Memory服务代理（高级编排服务）
-memory_service = env.get_service_proxy("tutorial_memory")
-
-# 存储记忆（自动同时存储到KV和VDB）
-memory_id = memory_service.store_memory(
-    content="用户询问了关于Python的问题",
-    vector=[0.1, 0.2, 0.3, ...],  # 内容的向量表示
-    session_id="session_123",
-    memory_type="conversation",
-    metadata={"topic": "programming", "language": "python"}
-)
-
-# 检索相关记忆（基于向量相似性）
-related_memories = memory_service.retrieve_memories(
-    query_vector=[0.1, 0.2, 0.3, ...],
-    session_id="session_123",
-    top_k=5
-)
-
-# 文本搜索记忆
-search_results = memory_service.search_memories(
-    query="Python",
-    session_id="session_123",
-    top_k=10
-)
-
-# 获取会话的所有记忆
-session_memories = memory_service.get_session_memories("session_123")
-'''
-        print(usage_example)
-        
-        print("🎯 Expected Results:")
-        print("   store_memory() -> 'memory_uuid_123'")
-        print("   retrieve_memories() -> [{'id': 'memory_uuid_123', 'score': 0.92, ...}]")
-        print("   search_memories() -> [{'id': 'memory_uuid_123', 'content': '...', ...}]")
-    
-    def demonstrate_api_composition(self):
-        """演示如何组合使用多个API"""
-        print("\n🔗 API Composition Tutorial")
-        print("-" * 40)
-        
-        print("💡 实际应用场景: 智能问答系统")
-        
-        composition_example = '''
-class IntelligentQASystem:
-    """智能问答系统 - 展示API组合使用"""
-    
-    def __init__(self, env):
-        # 获取各种服务代理
-        self.kv_service = env.get_service_proxy("tutorial_kv")
-        self.vdb_service = env.get_service_proxy("tutorial_vdb")
-        self.memory_service = env.get_service_proxy("tutorial_memory")
-    
-    async def process_question(self, user_id: str, question: str):
-        """处理用户问题"""
-        
-        # 1. 从KV服务获取用户上下文
-        user_context = self.kv_service.get(f"user_context:{user_id}")
-        
-        # 2. 将问题转换为向量（使用embedding工具）
-        question_vector = embed_text(question)  # 假设的embedding函数
-        
-        # 3. 使用Memory服务检索相关记忆
-        related_memories = self.memory_service.retrieve_memories(
-            query_vector=question_vector,
-            session_id=user_context.get("session_id"),
-            top_k=5
-        )
-        
-        # 4. 直接在VDB中搜索知识库
-        knowledge_results = self.vdb_service.search(
-            query_vector=question_vector,
-            top_k=10,
-            similarity_threshold=0.7
-        )
-        
-        # 5. 生成回答（使用LLM）
-        answer = generate_answer(question, related_memories, knowledge_results)
-        
-        # 6. 存储新的对话记忆
-        self.memory_service.store_memory(
-            content=f"Q: {question}\\nA: {answer}",
-            vector=question_vector,
-            session_id=user_context.get("session_id"),
-            memory_type="qa_pair"
-        )
-        
-        # 7. 更新用户上下文
-        user_context["last_question"] = question
-        self.kv_service.put(f"user_context:{user_id}", user_context)
-        
-        return answer
-'''
-        print(composition_example)
-        
-        print("\n🎯 这个例子展示了:")
-        print("   ✅ KV服务用于快速的上下文存取")
-        print("   ✅ VDB服务用于语义相似性搜索")
-        print("   ✅ Memory服务用于高级记忆管理")
-        print("   ✅ 各服务协同工作完成复杂任务")
-    
-    def demonstrate_error_handling(self):
-        """演示API错误处理最佳实践"""
-        print("\n⚠️ Error Handling Best Practices")
-        print("-" * 40)
-        
-        error_handling_example = '''
-# 正确的错误处理方式
-try:
-    # 尝试获取服务代理
-    kv_service = env.get_service_proxy("tutorial_kv")
-    
-    # API调用
-    result = kv_service.get("some_key")
-    if result is None:
-        print("Key not found")
-    else:
-        print(f"Retrieved: {result}")
-        
-except ServiceNotAvailableError:
-    print("KV service is not available")
-except ServiceTimeoutError:
-    print("KV service call timed out")
-except Exception as e:
-    print(f"Unexpected error: {e}")
-
-# 批量操作的错误处理
-documents = [...]  # 大量文档
-batch_size = 100
-
-for i in range(0, len(documents), batch_size):
-    batch = documents[i:i+batch_size]
-    try:
-        doc_ids = vdb_service.add_vectors(batch)
-        print(f"Successfully added batch {i//batch_size + 1}")
-    except Exception as e:
-        print(f"Failed to add batch {i//batch_size + 1}: {e}")
-        # 可以选择重试或跳过
-'''
-        print(error_handling_example)
-    
-    def run_tutorial(self):
-        """运行完整的API教程"""
-        print("🎓 SAGE Services API Complete Tutorial")
-        print("=" * 60)
-        
-        self.demonstrate_kv_api()
-        self.demonstrate_vdb_api()
-        self.demonstrate_memory_api()
-        self.demonstrate_api_composition()
-        self.demonstrate_error_handling()
-        
-        print("\n🎉 Tutorial Complete!")
-        print("\n📚 Next Steps:")
-        print("   1. 查看具体服务的实现代码")
-        print("   2. 运行真实的集成测试")
-        print("   3. 在你的项目中集成SAGE服务")
-        print("   4. 参考API文档了解更多细节")
-
-
-def main():
-    """主函数"""
-    tutorial = ServiceAPITutorial()
-    tutorial.run_tutorial()
-
-
-if __name__ == "__main__":
-    main()

sage/middleware/examples/dag_microservices_demo.py

@@ -1,219 +0,0 @@
-"""
-SAGE 微服务架构使用示例
-展示如何在应用程序中注册和使用KV、VDB、Memory服务
-"""
-import asyncio
-import time
-from typing import List
-import numpy as np
-
-# 导入SAGE环境和服务
-from sage.core.api.local_environment import LocalEnvironment
-from sage.middleware.services import (
-    MemoryService,
-    create_kv_service_factory,
-    create_vdb_service_factory,
-    create_memory_service_factory,
-)
-
-
-class SampleApplication:
-    """示例应用程序，展示如何使用微服务架构"""
-    
-    def __init__(self):
-        # 创建SAGE环境
-        self.env = LocalEnvironment("microservices_demo", {})
-        
-    def setup_services(self):
-        """在应用中注册微服务"""
-        print("🔧 注册微服务到SAGE环境...")
-        
-        # 注册KV服务
-        kv_factory = create_kv_service_factory(
-            service_name="kv_service",
-            backend_type="memory",  # 使用内存后端
-            max_size=1000,
-            ttl_seconds=3600  # 1小时过期
-        )
-    self.env.register_service_factory("kv_service", kv_factory)
-        
-        # 注册VDB服务
-        vdb_factory = create_vdb_service_factory(
-            service_name="vdb_service",
-            embedding_dimension=384,
-            index_type="IndexFlatL2",
-        )
-        self.env.register_service_factory("vdb_service", vdb_factory)
-        
-        # 注册Memory编排服务
-        memory_factory = create_memory_service_factory(
-            service_name="memory_service",
-            kv_service_name="kv_service",
-            vdb_service_name="vdb_service"
-        )
-    self.env.register_service_factory("memory_service", memory_factory)
-        
-        print("✅ 所有服务已注册")
-    
-    def run_demo(self):
-        """运行演示"""
-        print("🚀 启动微服务演示")
-        print("=" * 50)
-        
-        # 设置服务
-        self.setup_services()
-        
-        # 创建一个简单的数据流来演示服务使用
-        data_stream = self.env.from_memory_source([
-            {"id": 1, "content": "用户询问了关于Python的问题", "session": "session_1"},
-            {"id": 2, "content": "AI助手回答了Python基础知识", "session": "session_1"},
-            {"id": 3, "content": "用户请求更多代码示例", "session": "session_1"},
-            {"id": 4, "content": "讨论了机器学习算法", "session": "session_2"},
-            {"id": 5, "content": "解释了神经网络原理", "session": "session_2"}
-        ])
-        
-        # 定义处理函数
-        def process_conversation(data):
-            """处理对话数据的函数"""
-            # 在这里我们可以使用服务调用
-            # 注意：在实际的SAGE函数中，可以通过 self.call_service 访问服务
-            
-            print(f"处理对话: {data['content'][:30]}...")
-            
-            # 模拟向量化（在实际应用中，这里会调用embedding服务）
-            content_vector = np.random.random(384).tolist()
-            
-            # 这里展示了服务调用的概念
-            # 在实际的SAGE函数中，代码会是这样：
-            # 
-            # # 存储到KV
-            # self.call_service["kv_service"].put(f"conv:{data['id']}", {
-            #     "content": data['content'],
-            #     "session": data['session'],
-            #     "timestamp": time.time()
-            # })
-            # 
-            # # 存储记忆
-            # memory_id = self.call_service["memory_service"].store_memory(
-            #     session_id=data['session'],
-            #     content=data['content'],
-            #     vector=content_vector,
-            #     memory_type="conversation"
-            # )
-            
-            return {
-                "processed": True,
-                "memory_id": f"mock_memory_{data['id']}",
-                "vector_dim": len(content_vector)
-            }
-        
-        # 应用处理函数
-        processed_stream = data_stream.map(process_conversation)
-        
-        # 执行并收集结果
-        print("\n📊 处理结果:")
-        results = processed_stream.collect()
-        
-        for i, result in enumerate(results, 1):
-            print(f"  {i}. ✅ 已处理 - Memory ID: {result['memory_id']}")
-        
-        print(f"\n🎯 总共处理了 {len(results)} 条对话记录")
-        
-        # 展示服务调用的概念
-        self.show_service_usage_concept()
-    
-    def show_service_usage_concept(self):
-        """展示服务使用概念"""
-        print("\n" + "=" * 50)
-        print("💡 在SAGE函数中使用服务的示例代码:")
-        print("=" * 50)
-        
-        example_code = '''
-# 在SAGE Function中使用微服务的示例
-
-class ConversationProcessor(BaseFunction):
-    """对话处理函数"""
-    
-    def process(self, conversation_data):
-        session_id = conversation_data['session_id']
-        content = conversation_data['content']
-        
-        # 1. 调用KV服务存储原始数据
-        kv_success = self.call_service["kv_service"].put(
-            f"raw:{session_id}", 
-            conversation_data
-        )
-        
-        # 2. 生成向量表示（假设有embedding服务）
-        vector = self.call_service["embedding_service"].encode(content)
-        
-        # 3. 调用Memory服务存储记忆
-        memory_id = self.call_service["memory_service"].store_memory(
-            session_id=session_id,
-            content=content,
-            vector=vector,
-            memory_type="conversation"
-        )
-        
-        # 4. 搜索相关历史记忆
-        related_memories = self.call_service["memory_service"].search_memories(
-            query_vector=vector,
-            session_id=session_id,
-            limit=5
-        )
-        
-        return {
-            "memory_id": memory_id,
-            "related_count": len(related_memories),
-            "kv_stored": kv_success
-        }
-
-# 在DAG中注册和使用
-def create_conversation_dag():
-    env = LocalEnvironment("conversation_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", MemoryService, create_memory_service_factory())
-    
-    # 创建数据流
-    stream = env.from_kafka_source(...)
-    
-    # 应用处理函数（自动访问服务）
-    processed = stream.map(ConversationProcessor())
-    
-    return processed
-        '''
-        
-        print(example_code)
-        print("\n" + "=" * 50)
-        print("🔍 关键概念:")
-        print("1. 服务作为Service Tasks在DAG中运行")
-        print("2. 函数通过 self.call_service[service_name] 调用服务")
-        print("3. 服务可以是本地任务或Ray分布式任务")
-        print("4. 应用程序控制服务的生命周期")
-        print("5. 服务间通过SAGE的队列机制通信")
-
-
-def main():
-    """主函数"""
-    app = SampleApplication()
-    
-    try:
-        app.run_demo()
-        print("\n✅ 演示完成!")
-        print("\n📖 查看更多信息:")
-        print("  - 微服务代码: packages/sage-middleware/src/sage/service/")
-        print("  - 使用指南: packages/sage-middleware/MICROSERVICES_GUIDE.md")
-        
-    except KeyboardInterrupt:
-        print("\n\n👋 演示被中断")
-    except Exception as e:
-        print(f"\n❌ 演示出错: {e}")
-        import traceback
-        traceback.print_exc()
-
-
-if __name__ == "__main__":
-    main()