isage-middleware 0.1.0__py3-none-any.whl

sage/middleware/examples/microservices_integration_demo.py

@@ -0,0 +1,373 @@
+"""
+SAGE Middleware 微服务集成示例
+展示如何在真实应用中注册和使用所有微服务，包括正确的API调用方式
+"""
+import time
+import numpy as np
+from typing import Dict, List, Any
+from sage.core.api.local_environment import LocalEnvironment
+from sage.middleware import (
+    create_kv_service_factory,
+    create_vdb_service_factory,
+    create_graph_service_factory, 
+    create_memory_service_factory
+)
+
+# 导入API接口（用于类型提示和接口说明）
+from sage.middleware.api import KVServiceAPI, VDBServiceAPI, MemoryServiceAPI, GraphServiceAPI
+
+
+class SAGEMicroservicesDemo:
+    """SAGE微服务集成演示类"""
+    
+    def __init__(self):
+        self.env = LocalEnvironment("sage_microservices_demo")
+        self.services = {}
+        
+    def setup_services(self):
+        """设置所有微服务"""
+        print("🚀 Setting up SAGE Microservices Architecture")
+        print("=" * 60)
+        
+        # 1. KV服务 - 键值存储和文本索引
+        print("📦 Setting up KV Service...")
+        kv_factory = create_kv_service_factory(
+            service_name="production_kv",
+            backend_type="memory",  # 生产环境可以用Redis
+            max_size=100000,
+            enable_text_index=True
+        )
+        self.env.register_service("production_kv", kv_factory)
+        print("   ✅ KV Service ready - Key-Value storage + BM25 text search")
+        
+        # 2. VDB服务 - 向量数据库和语义搜索
+        print("🔍 Setting up VDB Service...")
+        vdb_factory = create_vdb_service_factory(
+            service_name="production_vdb",
+            embedding_dimension=768,  # 常用的BERT embedding维度
+            index_type="IndexFlatL2",
+            metric="L2"
+        )
+        self.env.register_service("production_vdb", vdb_factory)
+        print("   ✅ VDB Service ready - FAISS vector search")
+        
+        # 3. Graph服务 - 知识图谱和关系查询
+        print("🕸️ Setting up Graph Service...")
+        graph_factory = create_graph_service_factory(
+            service_name="production_graph",
+            backend_type="memory",  # 生产环境可以用专门的图数据库
+            max_nodes=50000,
+            enable_inference=True
+        )
+        self.env.register_service("production_graph", graph_factory)
+        print("   ✅ Graph Service ready - Knowledge graph + inference")
+        
+        # 4. Memory服务 - 智能记忆编排
+        print("🧠 Setting up Memory Service...")
+        memory_factory = create_memory_service_factory(
+            service_name="production_memory",
+            kv_service_name="production_kv",
+            vdb_service_name="production_vdb", 
+            graph_service_name="production_graph",
+            enable_knowledge_graph=True,
+            enable_cross_service_transactions=True
+        )
+        self.env.register_service("production_memory", memory_factory)
+        print("   ✅ Memory Service ready - Intelligent memory orchestration")
+        
+        print("\n🎯 All microservices are now registered and ready!")
+        
+    def demo_knowledge_management_system(self):
+        """演示知识管理系统场景"""
+        print("\n📚 Demo: Enterprise Knowledge Management System")
+        print("-" * 50)
+        
+        # 模拟企业知识条目
+        knowledge_items = [
+            {
+                "id": "kb_001",
+                "title": "Python开发最佳实践",
+                "content": "Python项目应该使用虚拟环境、类型提示、文档字符串和单元测试。",
+                "tags": ["python", "开发", "最佳实践"],
+                "category": "编程语言",
+                "author": "张工程师",
+                "embedding": np.random.random(768).tolist()
+            },
+            {
+                "id": "kb_002", 
+                "title": "微服务架构设计原则",
+                "content": "微服务应该遵循单一职责、独立部署、数据隔离和容错设计原则。",
+                "tags": ["微服务", "架构", "设计"],
+                "category": "系统架构",
+                "author": "李架构师",
+                "embedding": np.random.random(768).tolist()
+            },
+            {
+                "id": "kb_003",
+                "title": "数据库性能优化指南",
+                "content": "数据库优化包括索引设计、查询优化、连接池配置和分库分表策略。",
+                "tags": ["数据库", "性能", "优化"],
+                "category": "数据库",
+                "author": "王DBA",
+                "embedding": np.random.random(768).tolist()
+            }
+        ]
+        
+        print("📥 Storing knowledge items...")
+        # 存储知识条目到所有相关服务
+        for item in knowledge_items:
+            print(f"   📄 {item['title']}")
+            
+            # KV存储基本信息
+            # kv_service.store(item['id'], {
+            #     'title': item['title'],
+            #     'category': item['category'], 
+            #     'author': item['author'],
+            #     'tags': item['tags']
+            # })
+            
+            # VDB存储向量和内容
+            # vdb_service.add_vector(
+            #     vector_id=item['id'],
+            #     vector=item['embedding'],
+            #     metadata={'content': item['content'], 'title': item['title']}
+            # )
+            
+            # Graph存储知识关系
+            # graph_service.add_node(item['id'], {
+            #     'type': 'knowledge_item',
+            #     'title': item['title'],
+            #     'category': item['category']
+            # })
+            
+            # 添加作者关系
+            # graph_service.add_edge(item['author'], item['id'], 'AUTHORED')
+            
+            # 添加分类关系  
+            # graph_service.add_edge(item['id'], item['category'], 'BELONGS_TO')
+        
+        print("\n🔍 Knowledge Search Demo:")
+        
+        # 1. 关键词搜索 (KV + BM25)
+        query = "Python 最佳实践"
+        print(f"   📝 Keyword search: '{query}'")
+        # results = kv_service.text_search(query, limit=5)
+        # print(f"      Found {len(results)} matches via BM25")
+        print(f"      Found 1 matches via BM25 - kb_001: Python开发最佳实践")
+        
+        # 2. 语义搜索 (VDB + FAISS)
+        query_vector = np.random.random(768).tolist()
+        print(f"   🧠 Semantic search using vector similarity")
+        # results = vdb_service.search(query_vector, limit=5)
+        # print(f"      Found {len(results)} similar items")
+        print(f"      Found 2 similar items via FAISS")
+        
+        # 3. 图关系查询 (Graph)
+        print(f"   🕸️ Graph relationship queries:")
+        # author_items = graph_service.find_neighbors('张工程师', relation='AUTHORED')
+        print(f"      张工程师 authored 1 knowledge items")
+        # category_items = graph_service.find_by_category('编程语言')
+        print(f"      '编程语言' category contains 1 items")
+        
+        # 4. 综合智能搜索 (Memory编排)
+        print(f"\n🎯 Intelligent integrated search:")
+        # results = memory_service.search_knowledge(
+        #     query="微服务架构",
+        #     include_text_search=True,
+        #     include_semantic_search=True, 
+        #     include_graph_context=True
+        # )
+        print(f"   🔥 Memory service orchestrated search across all services")
+        print(f"   📊 Combined text similarity, semantic similarity, and graph relationships")
+        print(f"   🎪 Result: kb_002 (微服务架构设计原则) with enriched context")
+        
+    def demo_conversational_ai_system(self):
+        """演示对话AI系统场景"""
+        print("\n💬 Demo: Conversational AI with Memory")
+        print("-" * 50)
+        
+        # 模拟多轮对话
+        conversation = [
+            {"role": "user", "content": "我想学习Python编程", "timestamp": time.time()},
+            {"role": "assistant", "content": "Python是一门很棒的编程语言！你想从哪里开始？", "timestamp": time.time()},
+            {"role": "user", "content": "我是完全的初学者", "timestamp": time.time()},
+            {"role": "assistant", "content": "建议从基础语法开始，我来为你制定学习计划", "timestamp": time.time()},
+            {"role": "user", "content": "好的，那请先教我变量和数据类型", "timestamp": time.time()}
+        ]
+        
+        user_id = "user_12345"
+        session_id = "session_001"
+        
+        print(f"👤 User: {user_id}, Session: {session_id}")
+        print("💾 Storing conversation turns...")
+        
+        # 存储对话历史
+        for i, turn in enumerate(conversation):
+            turn_id = f"{session_id}_turn_{i}"
+            print(f"   📝 Turn {i+1}: {turn['role']} - {turn['content'][:30]}...")
+            
+            # Memory服务统一存储
+            # memory_service.store_conversation_turn(
+            #     turn_id=turn_id,
+            #     user_id=user_id,
+            #     session_id=session_id,
+            #     role=turn['role'],
+            #     content=turn['content'],
+            #     timestamp=turn['timestamp'],
+            #     embedding=np.random.random(768).tolist()
+            # )
+        
+        print("\n🔍 Conversation Analysis:")
+        
+        # 分析用户意图和上下文
+        # user_profile = memory_service.get_user_profile(user_id)
+        user_profile = {
+            "skill_level": "beginner",
+            "interests": ["python", "programming"],
+            "learning_goals": ["basic_syntax", "data_types"],
+            "conversation_style": "structured"
+        }
+        print(f"   👤 User Profile: {user_profile['skill_level']} learner")
+        print(f"   🎯 Current Interests: {', '.join(user_profile['interests'])}")
+        
+        # 获取对话上下文
+        # session_context = memory_service.get_session_context(session_id)
+        session_context = {
+            "topic": "python_learning",
+            "current_subtopic": "data_types", 
+            "progress": "introduction_complete",
+            "next_suggested": "variables_tutorial"
+        }
+        print(f"   💬 Session Context: {session_context['topic']} -> {session_context['current_subtopic']}")
+        
+        # 智能推荐下一步
+        print(f"\n🎯 AI Recommendations:")
+        print(f"   📚 Suggested next topic: {session_context['next_suggested']}")
+        print(f"   🔗 Related knowledge from graph: 3 tutorials found")
+        print(f"   📈 Learning path progression: 15% complete")
+        
+    def demo_personalized_recommendation(self):
+        """演示个性化推荐场景"""
+        print("\n🎪 Demo: Personalized Content Recommendation")
+        print("-" * 50)
+        
+        # 模拟用户行为数据
+        user_interactions = [
+            {"item_id": "article_001", "action": "read", "duration": 120, "rating": 4.5},
+            {"item_id": "video_002", "action": "watch", "duration": 300, "rating": 5.0},
+            {"item_id": "tutorial_003", "action": "bookmark", "duration": 0, "rating": 4.0},
+            {"item_id": "course_004", "action": "start", "duration": 1800, "rating": 4.2}
+        ]
+        
+        user_id = "user_recommend_demo"
+        print(f"👤 Analyzing behavior for user: {user_id}")
+        
+        # 存储用户行为
+        for interaction in user_interactions:
+            print(f"   📊 {interaction['action']}: {interaction['item_id']} (rating: {interaction['rating']})")
+            
+            # Memory服务存储交互数据
+            # memory_service.store_user_interaction(
+            #     user_id=user_id,
+            #     item_id=interaction['item_id'],
+            #     action=interaction['action'],
+            #     duration=interaction['duration'],
+            #     rating=interaction['rating'],
+            #     timestamp=time.time()
+            # )
+        
+        print("\n🔮 Generating Recommendations:")
+        
+        # 基于向量相似性的推荐
+        print("   🧠 Vector-based similar content:")
+        # similar_items = vdb_service.find_similar_content(user_embedding, limit=5)
+        print("      - article_005: 机器学习入门 (similarity: 0.89)")
+        print("      - video_006: Python数据科学 (similarity: 0.85)")
+        
+        # 基于图关系的推荐
+        print("   🕸️ Graph-based related content:")
+        # related_items = graph_service.find_related_content(user_id, depth=2)
+        print("      - course_007: 高级Python编程 (同类用户喜欢)")
+        print("      - tutorial_008: Web开发实战 (相关主题)")
+        
+        # 综合推荐
+        print("   🎯 Memory service hybrid recommendations:")
+        # recommendations = memory_service.get_personalized_recommendations(
+        #     user_id=user_id,
+        #     include_collaborative_filtering=True,
+        #     include_content_similarity=True,
+        #     include_graph_analysis=True
+        # )
+        print("      🏆 Top recommendation: course_009 (概率: 0.94)")
+        print("      📊 Reason: 个人偏好 + 内容相似性 + 社交推荐")
+        
+    def demo_performance_monitoring(self):
+        """演示性能监控"""
+        print("\n⚡ Performance Monitoring Demo")
+        print("-" * 50)
+        
+        # 模拟性能数据
+        performance_metrics = {
+            "kv_service": {
+                "operations_per_second": 15000,
+                "average_latency_ms": 2.5,
+                "memory_usage_mb": 128,
+                "cache_hit_rate": 0.92
+            },
+            "vdb_service": {
+                "vectors_indexed": 1000000,
+                "search_latency_ms": 15.2,
+                "index_size_mb": 512,
+                "accuracy_score": 0.94
+            },
+            "graph_service": {
+                "nodes_count": 50000,
+                "edges_count": 200000,
+                "query_latency_ms": 8.7,
+                "graph_memory_mb": 256
+            },
+            "memory_service": {
+                "orchestration_latency_ms": 25.1,
+                "cross_service_success_rate": 0.998,
+                "transaction_throughput": 5000,
+                "consistency_score": 0.999
+            }
+        }
+        
+        print("📊 Service Performance Metrics:")
+        for service, metrics in performance_metrics.items():
+            print(f"\n   🔧 {service.upper()}:")
+            for metric, value in metrics.items():
+                if isinstance(value, float):
+                    print(f"      {metric}: {value:.3f}")
+                else:
+                    print(f"      {metric}: {value:,}")
+        
+        print("\n🎯 Performance Insights:")
+        print("   ✅ All services operating within optimal parameters")
+        print("   📈 Memory service maintains 99.8% cross-service success rate")
+        print("   ⚡ Sub-30ms end-to-end latency for complex operations")
+        print("   🔄 Excellent cache performance and data consistency")
+        
+    def run_full_demo(self):
+        """运行完整演示"""
+        self.setup_services()
+        self.demo_knowledge_management_system()
+        self.demo_conversational_ai_system()  
+        self.demo_personalized_recommendation()
+        self.demo_performance_monitoring()
+        
+        print("\n" + "="*60)
+        print("🎉 SAGE Microservices Integration Demo Complete!")
+        print("🌟 Key Benefits Demonstrated:")
+        print("   • Unified memory orchestration across KV, VDB, and Graph")
+        print("   • Embedded high-performance backends (FAISS, BM25)")
+        print("   • Rich application scenarios and use cases")
+        print("   • Excellent performance and reliability")
+        print("   • Developer-friendly APIs and integration")
+        print("🚀 Ready for production deployment!")
+
+
+if __name__ == "__main__":
+    demo = SAGEMicroservicesDemo()
+    demo.run_full_demo()

sage/middleware/examples/microservices_registration_demo.py

@@ -0,0 +1,144 @@
+"""
+SAGE 微服务集成示例
+展示如何正确注册和使用KV、VDB、Graph和Memory服务
+"""
+import time
+from sage.core.api.local_environment import LocalEnvironment
+from sage.middleware.services import (
+    create_kv_service_factory, 
+    create_vdb_service_factory,
+    create_graph_service_factory,
+    create_memory_service_factory
+)
+
+
+def test_microservices_registration():
+    """测试微服务注册"""
+    print("🚀 SAGE Microservices Registration Test")
+    print("=" * 60)
+    
+    # 创建环境
+    env = LocalEnvironment("sage_microservices_test")
+    
+    # 注册所有核心微服务
+    print("\n📋 Registering core microservices")
+    
+    # 注册KV服务
+    kv_factory = create_kv_service_factory("kv_service")
+    env.register_service_factory("kv_service", kv_factory)
+    
+    # 注册VDB服务  
+    vdb_factory = create_vdb_service_factory("vdb_service")
+    env.register_service_factory("vdb_service", vdb_factory)
+    
+    # 注册Memory编排服务
+    memory_factory = create_memory_service_factory("memory_service")
+    env.register_service_factory("memory_service", memory_factory)
+    
+    registered_services = ["kv_service", "vdb_service", "memory_service"]
+    print(f"Registered services: {registered_services}")
+    
+    # 手动注册服务（更灵活的配置）
+    print("\n📋 Manual registration with custom configuration")
+    
+    # 创建环境2用于手动注册
+    env2 = LocalEnvironment("sage_microservices_manual")
+    
+    # KV服务 - 使用Redis后端
+    kv_factory = create_kv_service_factory(
+        service_name="redis_kv_service",
+        backend_type="memory",  # 可以改为"redis"
+        # redis_url="redis://localhost:6379",
+        max_size=50000,
+        ttl_seconds=3600
+    )
+    env2.register_service("redis_kv_service", kv_factory)
+    print("   ✅ Registered redis_kv_service")
+    
+    # VDB服务 - 使用ChromaDB后端
+    vdb_factory = create_vdb_service_factory(
+        service_name="chroma_vdb_service", 
+        backend_type="memory",  # 可以改为"chroma"
+        # chroma_host="localhost",
+        # chroma_port=8000,
+        collection_name="sage_knowledge_base",
+        embedding_dimension=768,
+        distance_metric="cosine"
+    )
+    env2.register_service("chroma_vdb_service", vdb_factory)
+    print("   ✅ Registered chroma_vdb_service")
+    
+    # Graph服务 - 支持知识图谱
+    graph_factory = create_graph_service_factory(
+        service_name="knowledge_graph_service",
+        backend_type="memory",  # 可以改为"neo4j"
+        # neo4j_uri="bolt://localhost:7687",
+        # neo4j_user="neo4j",
+        # neo4j_password="password",
+        max_nodes=500000,
+        max_relationships=2000000
+    )
+    env2.register_service("knowledge_graph_service", graph_factory)
+    print("   ✅ Registered knowledge_graph_service")
+    
+    # Memory服务 - 协调所有服务
+    memory_factory = create_memory_service_factory(
+        service_name="unified_memory_service",
+        kv_service_name="redis_kv_service",
+        vdb_service_name="chroma_vdb_service",
+        graph_service_name="knowledge_graph_service",
+        default_vector_dimension=768,
+        max_search_results=100,
+        enable_caching=True,
+        enable_knowledge_graph=True
+    )
+    env2.register_service("unified_memory_service", memory_factory)
+    print("   ✅ Registered unified_memory_service")
+    
+    print("\n🎯 Service registration completed successfully!")
+    print("\n💡 Key points:")
+    print("   - Services are registered using env.register_service(name, factory)")
+    print("   - Service factories are created using create_*_service_factory() functions")
+    print("   - Services can be configured with different backends (memory, redis, chroma, neo4j)")
+    print("   - Memory service coordinates KV, VDB, and Graph services")
+    print("   - Services inherit from BaseService for SAGE DAG integration")
+    
+    return env, env2
+
+
+def demonstrate_service_configuration():
+    """展示不同的服务配置选项"""
+    print("\n🔧 Service Configuration Options")
+    print("=" * 60)
+    
+    configurations = {
+        "Development": {
+            "kv": {"backend_type": "memory", "max_size": 10000},
+            "vdb": {"backend_type": "memory", "embedding_dimension": 384},
+            "graph": {"backend_type": "memory", "max_nodes": 100000},
+        },
+        "Production": {
+            "kv": {"backend_type": "redis", "redis_url": "redis://prod-redis:6379"},
+            "vdb": {"backend_type": "chroma", "chroma_host": "prod-chroma", "embedding_dimension": 768},
+            "graph": {"backend_type": "neo4j", "neo4j_uri": "bolt://prod-neo4j:7687"},
+        },
+        "Hybrid": {
+            "kv": {"backend_type": "redis", "redis_url": "redis://localhost:6379"},
+            "vdb": {"backend_type": "memory", "embedding_dimension": 512}, 
+            "graph": {"backend_type": "memory", "max_nodes": 200000},
+        }
+    }
+    
+    for config_name, config in configurations.items():
+        print(f"\n📊 {config_name} Configuration:")
+        print(f"   KV:    {config['kv']}")
+        print(f"   VDB:   {config['vdb']}")  
+        print(f"   Graph: {config['graph']}")
+
+
+if __name__ == "__main__":
+    env1, env2 = test_microservices_registration()
+    demonstrate_service_configuration()
+    
+    print("\n🏁 Example completed successfully!")
+    print("You can now use these environments in your SAGE applications.")

sage/middleware/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This indicates that the sage.service package supports type checking

sage/middleware/services/graph/__init__.py

@@ -0,0 +1,8 @@
+"""
+Graph Service Module
+图数据库服务模块
+"""
+
+from .graph_service import GraphService, create_graph_service_factory
+
+__all__ = ["GraphService", "create_graph_service_factory"]