isage-middleware 0.1.1__py3-none-any.whl → 0.1.3.1__py3-none-any.whl

sage/middleware/{enterprise → components}/sage_db/sage_db.py

@@ -1,218 +1,10 @@
 """
-SAGE DB - 高性能向量数据库
+SAGE DB - High-performance vector database with FAISS backend
 
-直接导出 C++ 扩展中的类和函数
+This module provides a Python interface to the SAGE DB vector database,
+which supports efficient similarity search with metadata filtering.
 """
 
-# 直接从 C++ 扩展导入所有必要的类
-try:
-    from ._sage_db import (
-        SageDB,
-        DatabaseConfig,
-        IndexType,
-        DistanceMetric,
-        QueryResult,
-        SearchParams,
-        SageDBException,
-        create_database,
-        index_type_to_string,
-        string_to_index_type,
-        distance_metric_to_string,
-        string_to_distance_metric
-    )
-    print("✓ SAGE DB C++ extension loaded successfully")
-except ImportError as e:
-    raise ImportError(f"Failed to import SAGE DB C++ extension: {e}")
-
-# 导出所有API
-__all__ = [
-    'SageDB',
-    'DatabaseConfig', 
-    'IndexType',
-    'DistanceMetric',
-    'QueryResult',
-    'SearchParams',
-    'SageDBException',
-    'create_database',
-    'index_type_to_string',
-    'string_to_index_type',
-    'distance_metric_to_string',
-    'string_to_distance_metric'
-]
-
-import numpy as np
-from typing import List, Dict, Any, Optional, Callable, Tuple, Union
-
-# 尝试导入C++扩展
-try:
-    from . import _sage_db
-    _cpp_available = True
-except ImportError:
-    try:
-        import _sage_db
-        _cpp_available = True
-    except ImportError:
-        _cpp_available = False
-        raise ImportError("SAGE DB C++ extension not available")
-
-# 重新导出C++类和枚举
-IndexType = _sage_db.IndexType
-DistanceMetric = _sage_db.DistanceMetric
-QueryResult = _sage_db.QueryResult
-SearchParams = _sage_db.SearchParams
-DatabaseConfig = _sage_db.DatabaseConfig
-SageDBException = _sage_db.SageDBException
-
-class SageDB:
-    """
-    High-performance vector database with FAISS backend.
-    
-    Supports efficient similarity search, metadata filtering, and hybrid search.
-    """
-    
-    def __init__(self, dimension: int, 
-                 index_type: IndexType = IndexType.AUTO,
-                 metric: DistanceMetric = DistanceMetric.L2):
-        """
-        Initialize a new SageDB instance.
-        
-        Args:
-            dimension: Vector dimension
-            index_type: Index type for similarity search
-            metric: Distance metric
-        """
-        self._db = _sage_db.create_database(dimension, index_type, metric)
-    
-    @classmethod
-    def from_config(cls, config: DatabaseConfig):
-        """Create SageDB from configuration object."""
-        instance = cls.__new__(cls)
-        instance._db = _sage_db.create_database(config)
-        return instance
-    
-    def add(self, vector: Union[List[float], np.ndarray], 
-            metadata: Optional[Dict[str, str]] = None) -> int:
-        """Add a single vector with optional metadata."""
-        if isinstance(vector, np.ndarray):
-            vector = vector.tolist()
-        return self._db.add(vector, metadata or {})
-    
-    def add_batch(self, vectors: Union[List[List[float]], np.ndarray],
-                  metadata: Optional[List[Dict[str, str]]] = None) -> List[int]:
-        """Add multiple vectors with optional metadata."""
-        if isinstance(vectors, np.ndarray):
-            if len(vectors.shape) != 2:
-                raise ValueError("Vectors array must be 2-dimensional")
-            return _sage_db.add_numpy(self._db, vectors, metadata or [])
-        else:
-            return self._db.add_batch(vectors, metadata or [])
-    
-    def search(self, query: Union[List[float], np.ndarray], 
-               k: int = 10, include_metadata: bool = True) -> List[QueryResult]:
-        """Search for similar vectors."""
-        if isinstance(query, np.ndarray):
-            return _sage_db.search_numpy(self._db, query, SearchParams(k))
-        return self._db.search(query, k, include_metadata)
-    
-    def search_with_params(self, query: Union[List[float], np.ndarray],
-                          params: SearchParams) -> List[QueryResult]:
-        """Search with custom parameters."""
-        if isinstance(query, np.ndarray):
-            return _sage_db.search_numpy(self._db, query, params)
-        return self._db.search(query, params)
-    
-    def filtered_search(self, query: Union[List[float], np.ndarray],
-                       params: SearchParams,
-                       filter_fn: Callable[[Dict[str, str]], bool]) -> List[QueryResult]:
-        """Search with metadata filtering."""
-        if isinstance(query, np.ndarray):
-            query = query.tolist()
-        return self._db.filtered_search(query, params, filter_fn)
-    
-    def remove(self, vector_id: int) -> bool:
-        """Remove a vector by ID."""
-        return self._db.remove(vector_id)
-    
-    def update(self, vector_id: int, vector: Union[List[float], np.ndarray],
-               metadata: Optional[Dict[str, str]] = None) -> bool:
-        """Update a vector and its metadata."""
-        if isinstance(vector, np.ndarray):
-            vector = vector.tolist()
-        return self._db.update(vector_id, vector, metadata or {})
-    
-    def build_index(self):
-        """Build the search index."""
-        self._db.build_index()
-    
-    def train_index(self, training_data: Optional[List[List[float]]] = None):
-        """Train the index with training data."""
-        self._db.train_index(training_data or [])
-    
-    def is_trained(self) -> bool:
-        """Check if the index is trained."""
-        return self._db.is_trained()
-    
-    def set_metadata(self, vector_id: int, metadata: Dict[str, str]) -> bool:
-        """Set metadata for a vector."""
-        return self._db.set_metadata(vector_id, metadata)
-    
-    def get_metadata(self, vector_id: int) -> Optional[Dict[str, str]]:
-        """Get metadata for a vector."""
-        result = self._db.get_metadata(vector_id)
-        return result if result is not None else None
-    
-    def find_by_metadata(self, key: str, value: str) -> List[int]:
-        """Find vectors by metadata key-value pair."""
-        return self._db.find_by_metadata(key, value)
-    
-    def save(self, filepath: str):
-        """Save database to file."""
-        self._db.save(filepath)
-    
-    def load(self, filepath: str):
-        """Load database from file."""
-        self._db.load(filepath)
-    
-    def size(self) -> int:
-        """Get number of vectors in database."""
-        return self._db.size()
-    
-    def dimension(self) -> int:
-        """Get vector dimension."""
-        return self._db.dimension()
-    
-    def index_type(self) -> IndexType:
-        """Get index type."""
-        return self._db.index_type()
-    
-    def config(self) -> DatabaseConfig:
-        """Get database configuration."""
-        return self._db.config()
-    
-    # 高级功能访问
-    def query_engine(self):
-        """Get query engine for advanced search operations."""
-        return self._db.query_engine()
-    
-    def vector_store(self):
-        """Get vector store for low-level operations."""
-        return self._db.vector_store()
-    
-    def metadata_store(self):
-        """Get metadata store for metadata operations."""
-        return self._db.metadata_store()
-
-# 导出的API
-__all__ = [
-    'SageDB',
-    'IndexType',
-    'DistanceMetric', 
-    'QueryResult',
-    'SearchParams',
-    'DatabaseConfig',
-    'SageDBException'
-]
-
 import numpy as np
 from typing import List, Dict, Any, Optional, Callable, Tuple, Union
 try:

sage/middleware/examples/api_usage_tutorial.py

@@ -10,10 +10,10 @@ from typing import List, Dict, Any
 from sage.middleware.api import KVServiceAPI, VDBServiceAPI, MemoryServiceAPI, GraphServiceAPI
 
 # 导入具体服务实现和工厂函数
-from sage.middleware import (
+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
+    create_kv_service_factory, create_vdb_service_factory,
+    create_memory_service_factory, create_graph_service_factory,
 )
 from sage.core.api.local_environment import LocalEnvironment
 

sage/middleware/examples/dag_microservices_demo.py

@@ -12,8 +12,8 @@ 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
+    create_vdb_service_factory,
+    create_memory_service_factory,
 )
 
 
@@ -35,16 +35,15 @@ class SampleApplication:
             max_size=1000,
             ttl_seconds=3600  # 1小时过期
         )
-        self.env.register_service("kv_service", kv_factory.service_class, kv_factory)
+    self.env.register_service_factory("kv_service", kv_factory)
         
         # 注册VDB服务
         vdb_factory = create_vdb_service_factory(
             service_name="vdb_service",
-            collection_name="demo_vectors",
-            dimension=384,
-            persist_directory="./demo_vectors"
+            embedding_dimension=384,
+            index_type="IndexFlatL2",
         )
-        self.env.register_service("vdb_service", vdb_factory.service_class, vdb_factory)
+        self.env.register_service_factory("vdb_service", vdb_factory)
         
         # 注册Memory编排服务
         memory_factory = create_memory_service_factory(
@@ -52,7 +51,7 @@ class SampleApplication:
             kv_service_name="kv_service",
             vdb_service_name="vdb_service"
         )
-        self.env.register_service("memory_service", memory_factory.service_class, memory_factory)
+    self.env.register_service_factory("memory_service", memory_factory)
         
         print("✅ 所有服务已注册")
     

sage/middleware/examples/microservices_integration_demo.py

@@ -6,7 +6,7 @@ import time
 import numpy as np
 from typing import Dict, List, Any
 from sage.core.api.local_environment import LocalEnvironment
-from sage.middleware import (
+from sage.middleware.services import (
     create_kv_service_factory,
     create_vdb_service_factory,
     create_graph_service_factory, 
@@ -37,29 +37,27 @@ class SAGEMicroservicesDemo:
             max_size=100000,
             enable_text_index=True
         )
-        self.env.register_service("production_kv", kv_factory)
+    self.env.register_service_factory("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维度
+            embedding_dimension=768,
             index_type="IndexFlatL2",
-            metric="L2"
         )
-        self.env.register_service("production_vdb", vdb_factory)
+        self.env.register_service_factory("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",  # 生产环境可以用专门的图数据库
+            backend_type="memory",
             max_nodes=50000,
-            enable_inference=True
         )
-        self.env.register_service("production_graph", graph_factory)
+        self.env.register_service_factory("production_graph", graph_factory)
         print("   ✅ Graph Service ready - Knowledge graph + inference")
         
         # 4. Memory服务 - 智能记忆编排
@@ -67,12 +65,11 @@ class SAGEMicroservicesDemo:
         memory_factory = create_memory_service_factory(
             service_name="production_memory",
             kv_service_name="production_kv",
-            vdb_service_name="production_vdb", 
+            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)
+        self.env.register_service_factory("production_memory", memory_factory)
         print("   ✅ Memory Service ready - Intelligent memory orchestration")
         
         print("\n🎯 All microservices are now registered and ready!")

sage/middleware/examples/microservices_registration_demo.py

@@ -5,10 +5,10 @@ SAGE 微服务集成示例
 import time
 from sage.core.api.local_environment import LocalEnvironment
 from sage.middleware.services import (
-    create_kv_service_factory, 
+    create_kv_service_factory,
     create_vdb_service_factory,
     create_graph_service_factory,
-    create_memory_service_factory
+    create_memory_service_factory,
 )
 
 
@@ -52,20 +52,16 @@ def test_microservices_registration():
         max_size=50000,
         ttl_seconds=3600
     )
-    env2.register_service("redis_kv_service", kv_factory)
+    env2.register_service_factory("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",
+        service_name="chroma_vdb_service",
         embedding_dimension=768,
-        distance_metric="cosine"
+        index_type="IndexFlatL2",
     )
-    env2.register_service("chroma_vdb_service", vdb_factory)
+    env2.register_service_factory("chroma_vdb_service", vdb_factory)
     print("   ✅ Registered chroma_vdb_service")
     
     # Graph服务 - 支持知识图谱
@@ -78,7 +74,7 @@ def test_microservices_registration():
         max_nodes=500000,
         max_relationships=2000000
     )
-    env2.register_service("knowledge_graph_service", graph_factory)
+    env2.register_service_factory("knowledge_graph_service", graph_factory)
     print("   ✅ Registered knowledge_graph_service")
     
     # Memory服务 - 协调所有服务
@@ -92,7 +88,7 @@ def test_microservices_registration():
         enable_caching=True,
         enable_knowledge_graph=True
     )
-    env2.register_service("unified_memory_service", memory_factory)
+    env2.register_service_factory("unified_memory_service", memory_factory)
     print("   ✅ Registered unified_memory_service")
     
     print("\n🎯 Service registration completed successfully!")

sage/middleware/services/__init__.py

@@ -0,0 +1,56 @@
+"""
+SAGE - Streaming-Augmented Generative Execution
+"""
+
+# 动态版本加载
+def _load_version():
+    """从 sage-common 包加载版本信息"""
+    try:
+        # 优先从 sage-common 包加载版本
+        from sage.common._version import __version__
+        return {
+            'version': __version__,
+            'author': 'SAGE Team',
+            'email': 'shuhao_zhang@hust.edu.cn'
+        }
+    except ImportError:
+        # 如果 sage-common 不可用，从项目根目录加载（开发环境）
+        try:
+            from pathlib import Path
+            current_file = Path(__file__).resolve()
+            # 根据当前文件位置计算到项目根目录的层数
+            parts = current_file.parts
+            sage_index = -1
+            for i, part in enumerate(parts):
+                if part == 'SAGE':
+                    sage_index = i
+                    break
+            
+            if sage_index >= 0:
+                root_dir = Path(*parts[:sage_index+1])
+                version_file = root_dir / "_version.py"
+                
+                if version_file.exists():
+                    version_globals = {}
+                    with open(version_file, 'r', encoding='utf-8') as f:
+                        exec(f.read(), version_globals)
+                    return {
+                        'version': version_globals.get('__version__', '0.1.3'),
+                        'author': version_globals.get('__author__', 'SAGE Team'),
+                        'email': version_globals.get('__email__', 'shuhao_zhang@hust.edu.cn')
+                    }
+        except Exception:
+            pass
+    
+    # 最后的默认值
+    return {
+        'version': '0.1.3',
+        'author': 'SAGE Team', 
+        'email': 'shuhao_zhang@hust.edu.cn'
+    }
+
+# 加载信息
+_info = _load_version()
+__version__ = _info['version']
+__author__ = _info['author']
+__email__ = _info['email']

sage/middleware/services/graph/__init__.py

@@ -1,8 +1,56 @@
 """
-Graph Service Module
-图数据库服务模块
+SAGE - Streaming-Augmented Generative Execution
 """
 
-from .graph_service import GraphService, create_graph_service_factory
+# 动态版本加载
+def _load_version():
+    """从 sage-common 包加载版本信息"""
+    try:
+        # 优先从 sage-common 包加载版本
+        from sage.common._version import __version__
+        return {
+            'version': __version__,
+            'author': 'SAGE Team',
+            'email': 'shuhao_zhang@hust.edu.cn'
+        }
+    except ImportError:
+        # 如果 sage-common 不可用，从项目根目录加载（开发环境）
+        try:
+            from pathlib import Path
+            current_file = Path(__file__).resolve()
+            # 根据当前文件位置计算到项目根目录的层数
+            parts = current_file.parts
+            sage_index = -1
+            for i, part in enumerate(parts):
+                if part == 'SAGE':
+                    sage_index = i
+                    break
+            
+            if sage_index >= 0:
+                root_dir = Path(*parts[:sage_index+1])
+                version_file = root_dir / "_version.py"
+                
+                if version_file.exists():
+                    version_globals = {}
+                    with open(version_file, 'r', encoding='utf-8') as f:
+                        exec(f.read(), version_globals)
+                    return {
+                        'version': version_globals.get('__version__', '0.1.3'),
+                        'author': version_globals.get('__author__', 'SAGE Team'),
+                        'email': version_globals.get('__email__', 'shuhao_zhang@hust.edu.cn')
+                    }
+        except Exception:
+            pass
+    
+    # 最后的默认值
+    return {
+        'version': '0.1.3',
+        'author': 'SAGE Team', 
+        'email': 'shuhao_zhang@hust.edu.cn'
+    }
 
-__all__ = ["GraphService", "create_graph_service_factory"]
+# 加载信息
+_info = _load_version()
+__version__ = _info['version']
+__author__ = _info['author']
+__email__ = _info['email']

sage/middleware/services/graph/examples/graph_demo.py

@@ -3,7 +3,7 @@ Graph Service 使用示例
 展示如何使用Graph微服务进行知识图谱构建和查询
 """
 from sage.core.api.local_environment import LocalEnvironment
-from sage.middleware.services.services.graph import create_graph_service_factory
+from sage.middleware.services.graph import create_graph_service_factory
 
 
 def test_graph_service():
@@ -21,7 +21,8 @@ def test_graph_service():
         max_nodes=10000,
         max_relationships=50000
     )
-    env.register_service("demo_graph_service", graph_factory)
+    # 使用服务工厂注册（与 SAGE Kernel 的 ServiceFactory 对齐）
+    env.register_service_factory("demo_graph_service", graph_factory)
     
     print("✅ Graph Service registered with memory backend")
     print("   - Max nodes: 10,000")

sage/middleware/services/graph/graph_service.py

@@ -371,6 +371,14 @@ class GraphService(BaseService):
     
     # Graph操作方法 - 这些方法可以通过服务调用机制被调用
     
+    # 兼容API：add_node(dict) 与 create_node(labels, properties, node_id)
+    def add_node(self, node: Dict[str, Any]) -> str:
+        """兼容 MemoryService 的 add_node 接口: {'id','labels','properties'}"""
+        labels = node.get("labels", []) or []
+        properties = node.get("properties", {}) or {}
+        node_id = node.get("id")
+        return self.create_node(labels=labels, properties=properties, node_id=node_id)
+
     def create_node(self, labels: List[str], properties: Dict[str, Any], 
                    node_id: Optional[str] = None) -> str:
         """创建节点"""
@@ -386,6 +394,17 @@ class GraphService(BaseService):
         self.logger.debug(f"Created node: {result}")
         return result
     
+    # 兼容API：add_relationship(dict) 与 create_relationship(from,to,type,...)
+    def add_relationship(self, rel: Dict[str, Any]) -> str:
+        """兼容 MemoryService 的 add_relationship 接口: {'from_node','to_node','rel_type','properties','id'}"""
+        return self.create_relationship(
+            from_node=rel.get("from_node"),
+            to_node=rel.get("to_node"),
+            rel_type=rel.get("rel_type"),
+            properties=rel.get("properties"),
+            rel_id=rel.get("id")
+        )
+
     def create_relationship(self, from_node: str, to_node: str, rel_type: str,
                           properties: Optional[Dict[str, Any]] = None,
                           rel_id: Optional[str] = None) -> str:
@@ -417,6 +436,55 @@ class GraphService(BaseService):
                 "created_at": node.created_at
             }
         return None
+
+    # 兼容 MemoryService 查询使用的便捷方法
+    def get_node_context(self, node_id: str, depth: int = 1) -> Dict[str, Any]:
+        """获取节点的邻域上下文（简单一层或多层展开）"""
+        context = {"node": self.get_node(node_id), "neighbors": [], "relationships": []}
+        if not context["node"]:
+            return context
+        rels = self.get_node_relationships(node_id, direction="both") if hasattr(self.backend, 'get_node_relationships') else []
+        context["relationships"] = rels
+        neighbor_ids = set()
+        for r in rels:
+            neighbor_ids.add(r.get("from_node") if isinstance(r, dict) else r.from_node)
+            neighbor_ids.add(r.get("to_node") if isinstance(r, dict) else r.to_node)
+        neighbor_ids.discard(node_id)
+        for nid in neighbor_ids:
+            n = self.get_node(nid)
+            if n:
+                context["neighbors"].append(n)
+        return context
+
+    def get_session_graph(self, session_id: str) -> Dict[str, Any]:
+        """根据会话ID返回简单的图统计（基于节点属性 session_id）"""
+        # 简单按属性筛选
+        try:
+            nodes = self.find_nodes(properties={"session_id": session_id})
+        except Exception:
+            nodes = []
+        node_ids = {n["id"] if isinstance(n, dict) else n.id for n in nodes}
+        # 关系筛选
+        relationships = []
+        if hasattr(self.backend, 'relationships'):
+            for rel in getattr(self.backend, 'relationships', {}).values():
+                src = rel.get("from_node") if isinstance(rel, dict) else rel.from_node
+                dst = rel.get("to_node") if isinstance(rel, dict) else rel.to_node
+                if src in node_ids or dst in node_ids:
+                    relationships.append({
+                        "id": rel.get("id") if isinstance(rel, dict) else rel.id,
+                        "from_node": src,
+                        "to_node": dst,
+                        "rel_type": rel.get("rel_type") if isinstance(rel, dict) else rel.rel_type,
+                        "properties": rel.get("properties") if isinstance(rel, dict) else rel.properties,
+                    })
+        return {
+            "session_id": session_id,
+            "node_count": len(nodes),
+            "relationship_count": len(relationships),
+            "nodes": nodes,
+            "relationships": relationships,
+        }
     
     def find_nodes(self, labels: Optional[List[str]] = None,
                   properties: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]: