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

sage/middleware/components/sage_db/__init__.py

@@ -1,56 +1,116 @@
+"""SageVDB compatibility layer for SAGE.
+
+SageVDB has been migrated to an independent PyPI package.
+
+Installation:
+    pip install isage-vdb
+
+This module re-exports SageVDB classes from the sagevdb package
+for backward-compatible import paths within SAGE.
+
+Important:
+    - PyPI package name: isage-vdb (with hyphen and 'i' prefix)
+    - Python import name: sagevdb (no 'i', no hyphen)
+
+For detailed migration information, see:
+    docs-public/docs_src/dev-notes/cross-layer/sagedb-independence-migration.md
 """
-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']
+import warnings
+
+# Re-export everything from sagevdb (Python import name, PyPI: isage-vdb)
+_SAGE_DB_AVAILABLE = False
+try:
+    from sagevdb import (
+        DatabaseConfig,
+        DistanceMetric,
+        IndexType,
+        MetadataStore,
+        QueryEngine,
+        QueryResult,
+        SageVDB,
+        SageVDBException,
+        SearchParams,
+        SearchStats,
+        VectorStore,
+        add_numpy,
+        create_database,
+        distance_metric_to_string,
+        index_type_to_string,
+        search_numpy,
+        string_to_distance_metric,
+        string_to_index_type,
+    )
+
+    _SAGE_DB_AVAILABLE = True
+except ImportError as e:
+    # Don't warn on import - only when actually trying to use SageVDB
+    # Store error message for later use
+    _SAGE_DB_IMPORT_ERROR = str(e)
+    pass
+    # Provide stub exports to prevent ImportError
+    SageVDB = None
+    IndexType = None
+    DistanceMetric = None
+    QueryResult = None
+    SearchParams = None
+    SearchStats = None
+    DatabaseConfig = None
+    MetadataStore = None
+    QueryEngine = None
+    VectorStore = None
+    SageVDBException = None
+    create_database = None
+    add_numpy = None
+    search_numpy = None
+    distance_metric_to_string = None
+    index_type_to_string = None
+    string_to_distance_metric = None
+    string_to_index_type = None
+
+# Import backend adapters
+try:
+    from .backend import SageVDBBackend  # noqa: F401
+except ImportError:
+    SageVDBBackend = None
+
+__all__ = [
+    # Core classes (may be None if not installed)
+    "SageVDB",
+    "IndexType",
+    "DistanceMetric",
+    "QueryResult",
+    "SearchParams",
+    "SearchStats",
+    "DatabaseConfig",
+    "MetadataStore",
+    "QueryEngine",
+    "VectorStore",
+    "SageVDBException",
+    # Factory functions
+    "create_database",
+    # Numpy utilities
+    "add_numpy",
+    "search_numpy",
+    # Conversion utilities
+    "distance_metric_to_string",
+    "index_type_to_string",
+    "string_to_distance_metric",
+    "string_to_index_type",
+    # Backend adapters
+    "SageVDBBackend",
+    # Availability flag
+    "_SAGE_DB_AVAILABLE",
+]
+
+
+def __getattr__(name):
+    """Provide friendly error message when SageVDB is not installed"""
+    if name in __all__ and not _SAGE_DB_AVAILABLE:
+        raise ImportError(
+            f"Cannot import '{name}' from sage.middleware.components.sage_db. "
+            "SageVDB is not installed. Please install it using:\n"
+            "  pip install isage-vdb\n"
+            "Note: PyPI package name is 'isage-vdb', Python import name is 'sagevdb'"
+        )
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

sage/middleware/components/sage_flow/__init__.py

@@ -0,0 +1,76 @@
+"""SageFlow compatibility layer for SAGE.
+
+SageFlow has been migrated to an independent PyPI package.
+
+Installation:
+    pip install isage-flow
+
+This module re-exports SageFlow classes from the isage-flow package
+for backward-compatible import paths within SAGE, and provides
+SAGE-specific services and wrappers.
+
+For detailed migration information, see:
+    docs-public/docs_src/dev-notes/cross-layer/sageflow-independence-migration.md
+"""
+
+import warnings
+
+# Import from PyPI package (isage-flow)
+_SAGE_FLOW_AVAILABLE = False
+try:
+    from sage_flow import (
+        DataType,
+        SimpleStreamSource,
+        Stream,
+        StreamEnvironment,
+        VectorData,
+        VectorRecord,
+        __author__,
+        __email__,
+        __version__,
+    )
+
+    _SAGE_FLOW_AVAILABLE = True
+except ImportError as e:
+    # Don't fail immediately - allow graceful degradation
+    warnings.warn(
+        f"SAGE Flow not available: {e}\n"
+        "Install with: pip install isage-flow\n"
+        "Some advanced streaming features will be unavailable.",
+        UserWarning,
+        stacklevel=2,
+    )
+    # Provide stub exports to prevent ImportError
+    DataType = None
+    SimpleStreamSource = None
+    Stream = None
+    StreamEnvironment = None
+    VectorData = None
+    VectorRecord = None
+    __version__ = "unavailable"
+    __author__ = "IntelliStream Team"
+    __email__ = "shuhao_zhang@hust.edu.cn"
+
+# SAGE-specific services (kept in SAGE repo)
+# Only import if sage_flow is available
+if _SAGE_FLOW_AVAILABLE:
+    from .python.micro_service.sage_flow_service import SageFlowService
+else:
+    SageFlowService = None
+
+__all__ = [
+    # Core API from isage-flow (may be None if not installed)
+    "StreamEnvironment",
+    "Stream",
+    "SimpleStreamSource",
+    "VectorData",
+    "VectorRecord",
+    "DataType",
+    "__version__",
+    "__author__",
+    "__email__",
+    # SAGE-specific services (may be None if isage-flow not installed)
+    "SageFlowService",
+    # Availability flag
+    "_SAGE_FLOW_AVAILABLE",
+]

sage/middleware/components/sage_flow/python/__init__.py

@@ -0,0 +1,14 @@
+"""Python bindings and wrappers for SAGE-Flow live here.
+
+This package is intended to house all Python-side modules for the component.
+"""
+
+# Try to import the C++ extension module
+# If this fails, sage_flow.py will handle the fallback logic
+try:
+    from . import _sage_flow  # noqa: F401  # type: ignore[import-not-found]
+
+    __all__ = ["_sage_flow"]
+except ImportError:
+    # sage_flow.py will handle finding and importing the .so file
+    __all__ = []

sage/middleware/components/sage_flow/python/micro_service/__init__.py

@@ -0,0 +1,4 @@
+# Expose SageFlowService from submodule
+from .sage_flow_service import SageFlowService
+
+__all__ = ["SageFlowService"]

sage/middleware/components/sage_mem/__init__.py

@@ -0,0 +1,83 @@
+"""
+SAGE-Mem: Memory Management Component for SAGE
+
+Provides memory management capabilities for RAG applications.
+This is a namespace package that can contain multiple memory implementations:
+- neuromem: Brain-inspired memory system (from isage-neuromem package)
+- future implementations can be added here
+
+Usage:
+    # Method 1: Import from neuromem subpackage (recommended)
+    from sage.middleware.components.sage_mem.neuromem import MemoryManager
+
+    # Method 2: Convenience imports from sage_mem root (if neuromem is installed)
+    from sage.middleware.components.sage_mem import MemoryManager
+"""
+
+# This is a namespace package - allow subpackages from different distributions
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+# Convenience re-exports from neuromem (optional, requires isage-neuromem installed)
+# These are lazy-loaded to avoid import errors if neuromem is not installed
+_NEUROMEM_AVAILABLE = False
+
+try:
+    # Try to import from the neuromem subpackage first (supports namespace merging)
+    from sage.middleware.components.sage_mem.neuromem import (
+        BaseMemoryCollection,
+        GraphMemoryCollection,
+        KVMemoryCollection,
+        MemoryManager,
+        VDBMemoryCollection,
+    )
+
+    try:
+        from sage.middleware.components.sage_mem.neuromem.services import (
+            BaseMemoryService,
+            MemoryServiceRegistry,
+            NeuromemServiceFactory,
+        )
+    except ImportError:
+        # Services might not be available in all neuromem versions
+        pass
+
+    # SimpleGraphIndex is in search_engine, not memory_collection
+    try:
+        from sage.middleware.components.sage_mem.neuromem.search_engine.graph_index import (
+            SimpleGraphIndex,
+        )
+    except ImportError:
+        SimpleGraphIndex = None
+
+    __all__ = [
+        # Core neuromem components
+        "MemoryManager",
+        "BaseMemoryCollection",
+        "VDBMemoryCollection",
+        "KVMemoryCollection",
+        "GraphMemoryCollection",
+        # Services (if available)
+        "BaseMemoryService",
+        "MemoryServiceRegistry",
+        "NeuromemServiceFactory",
+    ]
+
+    if SimpleGraphIndex is not None:
+        __all__.append("SimpleGraphIndex")
+
+    _NEUROMEM_AVAILABLE = True
+
+except (ImportError, FileNotFoundError, ModuleNotFoundError):
+    # Neuromem not installed - provide helpful error message via __getattr__
+    def __getattr__(name):
+        """Provide friendly error message when neuromem is not installed"""
+        raise ImportError(
+            f"Cannot import '{name}' from sage.middleware.components.sage_mem. "
+            "NeuroMem is not installed. Please install it using:\n"
+            "  pip install isage-neuromem\n"
+            "or install sage-middleware with neuromem support:\n"
+            "  pip install isage-middleware[neuromem]"
+        )
+
+    __all__ = []
+    _NEUROMEM_AVAILABLE = False

sage/middleware/components/sage_refiner/__init__.py

@@ -0,0 +1,103 @@
+"""
+SAGE Refiner - Context compression and refinement component
+===========================================================
+
+SageRefiner has been migrated to an independent PyPI package.
+
+Installation:
+    pip install isage-refiner
+
+This module re-exports SageRefiner classes from the isage-refiner package
+for backward-compatible import paths within SAGE, and provides
+SAGE-specific services and wrappers.
+
+For detailed migration information, see:
+    docs-public/docs_src/dev-notes/cross-layer/sagerefiner-independence-migration.md
+"""
+
+import warnings
+
+# Import from PyPI package (isage-refiner)
+_SAGE_REFINER_AVAILABLE = False
+try:
+    from sage_refiner import (
+        LongRefinerCompressor,
+        ProvenceCompressor,
+        RefinerAlgorithm,
+        RefinerConfig,
+        REFORMCompressor,
+        __author__,
+        __email__,
+        __version__,
+    )
+
+    _SAGE_REFINER_AVAILABLE = True
+except ImportError as e:
+    # Don't fail immediately - allow graceful degradation
+    warnings.warn(
+        f"SAGE Refiner not available: {e}\n"
+        "Install with: pip install isage-refiner\n"
+        "Context compression features will be unavailable.",
+        UserWarning,
+        stacklevel=2,
+    )
+    # Provide stub exports
+    LongRefinerCompressor = None
+    ProvenceCompressor = None
+    RefinerAlgorithm = None
+    RefinerConfig = None
+    REFORMCompressor = None
+    __version__ = "unavailable"
+    __author__ = "IntelliStream Team"
+    __email__ = "shuhao_zhang@hust.edu.cn"
+
+# SAGE-specific services (kept in SAGE repo)
+# Only import if base package is available
+if _SAGE_REFINER_AVAILABLE:
+    from .python.service import RefinerService
+else:
+    RefinerService = None
+
+# SAGE framework dependencies (optional, for integration)
+try:
+    from sage.libs.foundation.context.compression.algorithms import (
+        LongRefinerAlgorithm,
+        SimpleRefiner,
+    )
+    from sage.libs.foundation.context.compression.refiner import (
+        BaseRefiner,
+        RefineResult,
+        RefinerMetrics,
+    )
+
+    _SAGE_LIBS_AVAILABLE = True
+except ImportError:
+    _SAGE_LIBS_AVAILABLE = False
+    LongRefinerAlgorithm = None
+    SimpleRefiner = None
+    BaseRefiner = None
+    RefineResult = None
+    RefinerMetrics = None
+
+__all__ = [
+    # Core API from isage-refiner (may be None if not installed)
+    "LongRefinerCompressor",
+    "REFORMCompressor",
+    "ProvenceCompressor",
+    "RefinerConfig",
+    "RefinerAlgorithm",
+    "__version__",
+    "__author__",
+    "__email__",
+    # SAGE-specific services
+    "RefinerService",
+    # SAGE framework integration (optional)
+    "LongRefinerAlgorithm",
+    "SimpleRefiner",
+    "BaseRefiner",
+    "RefineResult",
+    "RefinerMetrics",
+    # Availability flags
+    "_SAGE_REFINER_AVAILABLE",
+    "_SAGE_LIBS_AVAILABLE",
+]

sage/middleware/components/sage_refiner/python/__init__.py

@@ -0,0 +1,38 @@
+"""
+SAGE Refiner Python Adapter Layer
+==================================
+
+This module provides the SAGE-specific adapter layer for sage_refiner.
+It wraps the standalone sage_refiner library with SAGE framework integration.
+
+For standalone usage of sage_refiner, import from:
+    sage_refiner (PyPI package)
+"""
+
+# Import from sage_refiner submodule
+from sage_refiner import (
+    RefinerAlgorithm,
+    RefinerConfig,
+)
+
+from sage.libs.foundation.context.compression.refiner import (
+    BaseRefiner,
+    RefineResult,
+    RefinerMetrics,
+)
+
+# Global Context Service
+from sage.middleware.components.sage_refiner.python.context_service import ContextService
+
+# SAGE-specific adapter
+from sage.middleware.components.sage_refiner.python.service import RefinerService
+
+__all__ = [
+    "BaseRefiner",
+    "RefineResult",
+    "RefinerMetrics",
+    "RefinerConfig",
+    "RefinerAlgorithm",
+    "RefinerService",
+    "ContextService",
+]

sage/middleware/components/sage_tsdb/__init__.py

@@ -0,0 +1,81 @@
+"""
+SAGE-TSDB: Time Series Database Component for SAGE
+
+Provides efficient time series data storage, querying, and processing capabilities
+for streaming and historical data analysis.
+
+Note: SAGE TSDB core is now an independent PyPI package (isage-tsdb).
+This module provides backward-compatible wrappers and SAGE-specific services.
+"""
+
+import warnings
+
+# Import from PyPI package (isage-tsdb)
+_SAGE_TSDB_AVAILABLE = False
+try:
+    from sage_tsdb import (
+        QueryConfig,
+        TimeRange,
+        TimeSeriesData,
+        TimeSeriesDB,
+        TimeSeriesIndex,
+    )
+
+    # Backward compatibility alias
+    SageTSDB = TimeSeriesDB
+    _SAGE_TSDB_AVAILABLE = True
+except ImportError as e:
+    # Don't fail immediately - allow graceful degradation
+    warnings.warn(
+        f"SAGE TSDB not available: {e}\n"
+        "Install with: pip install isage-tsdb\n"
+        "Time series features will be unavailable.",
+        UserWarning,
+        stacklevel=2,
+    )
+    # Provide stub exports
+    SageTSDB = None
+    TimeSeriesDB = None
+    TimeSeriesData = None
+    QueryConfig = None
+    TimeRange = None
+    TimeSeriesIndex = None
+
+# Algorithms (SAGE-specific extensions)
+# Only import if base package is available
+if _SAGE_TSDB_AVAILABLE:
+    from .python.algorithms import (
+        OutOfOrderStreamJoin,
+        TimeSeriesAlgorithm,
+        WindowAggregator,
+    )
+
+    # Micro-service wrapper (SAGE-specific)
+    from .python.micro_service.sage_tsdb_service import (
+        SageTSDBService,
+        SageTSDBServiceConfig,
+    )
+else:
+    # Stub classes if TSDB not available
+    TimeSeriesAlgorithm = None
+    OutOfOrderStreamJoin = None
+    WindowAggregator = None
+    SageTSDBService = None
+    SageTSDBServiceConfig = None
+
+__all__ = [
+    # Core API (may be None if not installed)
+    "SageTSDB",
+    "TimeSeriesData",
+    "QueryConfig",
+    "TimeRange",
+    # Service
+    "SageTSDBService",
+    "SageTSDBServiceConfig",
+    # Algorithms
+    "TimeSeriesAlgorithm",
+    "OutOfOrderStreamJoin",
+    "WindowAggregator",
+    # Availability flag
+    "_SAGE_TSDB_AVAILABLE",
+]