stellar-memory 2.0.0__tar.gz → 3.0.0__tar.gz

{stellar_memory-2.0.0/stellar_memory.egg-info → stellar_memory-3.0.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.1
 Name: stellar-memory
-Version: 2.0.0
-Summary: A celestial-structure-based AI memory management system - Give any AI human-like memory
+Version: 3.0.0
+Summary: AI Memory Platform SDK - Give any AI human-like memory
 Author: Stellar Memory Contributors
 License: MIT
 Project-URL: Homepage, https://stellar-memory.com/
 Project-URL: Repository, https://github.com/sangjun0000/stellar-memory
 Project-URL: Documentation, https://stellar-memory.com/docs/
 Project-URL: Changelog, https://github.com/sangjun0000/stellar-memory/blob/main/CHANGELOG.md
-Keywords: ai,memory,llm,mcp,recall,context
+Keywords: ai,memory,llm,mcp,recall,context,sdk,platform
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -35,6 +35,12 @@ Provides-Extra: mcp
 Requires-Dist: mcp[cli]>=1.2.0; extra == "mcp"
 Provides-Extra: cli
 Requires-Dist: mcp[cli]>=1.2.0; extra == "cli"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110.0; extra == "server"
+Requires-Dist: uvicorn>=0.29.0; extra == "server"
+Provides-Extra: dashboard
+Requires-Dist: fastapi>=0.110.0; extra == "dashboard"
+Requires-Dist: uvicorn>=0.29.0; extra == "dashboard"
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
 Provides-Extra: redis
@@ -45,16 +51,6 @@ Provides-Extra: sync
 Requires-Dist: websockets>=12.0; extra == "sync"
 Provides-Extra: connectors
 Requires-Dist: httpx>=0.27.0; extra == "connectors"
-Provides-Extra: server
-Requires-Dist: fastapi>=0.110.0; extra == "server"
-Requires-Dist: uvicorn>=0.29.0; extra == "server"
-Provides-Extra: dashboard
-Requires-Dist: fastapi>=0.110.0; extra == "dashboard"
-Requires-Dist: uvicorn>=0.29.0; extra == "dashboard"
-Provides-Extra: billing
-Requires-Dist: stripe>=7.0.0; extra == "billing"
-Requires-Dist: httpx>=0.27.0; extra == "billing"
-Requires-Dist: asyncpg>=0.29.0; extra == "billing"
 Provides-Extra: adapters
 Requires-Dist: langchain-core>=0.1.0; extra == "adapters"
 Provides-Extra: full
@@ -71,7 +67,6 @@ Requires-Dist: httpx>=0.27.0; extra == "full"
 Requires-Dist: fastapi>=0.110.0; extra == "full"
 Requires-Dist: uvicorn>=0.29.0; extra == "full"
 Requires-Dist: langchain-core>=0.1.0; extra == "full"
-Requires-Dist: stripe>=7.0.0; extra == "full"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
 Provides-Extra: dev

stellar_memory-3.0.0/celestial_engine/__init__.py

@@ -0,0 +1,67 @@
+"""Celestial Memory Engine - DEPRECATED in v3.0.
+
+Use stellar_memory instead::
+
+    # Before:
+    from celestial_engine import CelestialMemory
+    memory = CelestialMemory()
+
+    # After:
+    from stellar_memory import StellarBuilder, Preset
+    memory = StellarBuilder(Preset.MINIMAL).with_sqlite("celestial_memory.db").build()
+
+See migration guide: docs/migration-v2-to-v3.md
+"""
+
+from __future__ import annotations
+
+import warnings
+
+warnings.warn(
+    "celestial_engine is deprecated in v3.0. Use stellar_memory instead. "
+    "See docs/migration-v2-to-v3.md for migration guide.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Thin shim: re-export stellar_memory classes under old names
+from stellar_memory import StellarMemory as CelestialMemory  # noqa: F401
+from stellar_memory import StellarBuilder  # noqa: F401
+from stellar_memory import Preset  # noqa: F401
+from stellar_memory import StellarConfig  # noqa: F401
+from stellar_memory import MemoryItem as CelestialItem  # noqa: F401
+from stellar_memory import MemoryStats  # noqa: F401
+from stellar_memory.models import ScoreBreakdown, ReorbitResult  # noqa: F401
+from stellar_memory.config import (  # noqa: F401
+    MemoryFunctionConfig,
+    ZoneConfig,
+    DEFAULT_ZONES,
+)
+
+# Legacy evaluator imports
+from stellar_memory.protocols import ImportanceEvaluator  # noqa: F401
+from stellar_memory.importance_evaluator import (  # noqa: F401
+    RuleBasedEvaluator,
+    LLMEvaluator,
+    NullEvaluator as DefaultEvaluator,
+)
+
+__version__ = "3.0.0-deprecated"
+
+__all__ = [
+    "CelestialMemory",
+    "CelestialItem",
+    "StellarBuilder",
+    "Preset",
+    "StellarConfig",
+    "MemoryStats",
+    "MemoryFunctionConfig",
+    "ZoneConfig",
+    "ScoreBreakdown",
+    "ReorbitResult",
+    "DEFAULT_ZONES",
+    "ImportanceEvaluator",
+    "DefaultEvaluator",
+    "RuleBasedEvaluator",
+    "LLMEvaluator",
+]

{stellar_memory-2.0.0 → stellar_memory-3.0.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "stellar-memory"
-version = "2.0.0"
-description = "A celestial-structure-based AI memory management system - Give any AI human-like memory"
+version = "3.0.0"
+description = "AI Memory Platform SDK - Give any AI human-like memory"
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
@@ -16,7 +16,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-keywords = ["ai", "memory", "llm", "mcp", "recall", "context"]
+keywords = ["ai", "memory", "llm", "mcp", "recall", "context", "sdk", "platform"]
 dependencies = []
 
 [project.urls]
@@ -29,35 +29,32 @@ Changelog = "https://github.com/sangjun0000/stellar-memory/blob/main/CHANGELOG.m
 stellar-memory = "stellar_memory.cli:main"
 
 [project.optional-dependencies]
-# Core AI features
+# AI Features
 embedding = ["sentence-transformers>=2.2.0"]
 llm = ["anthropic>=0.18.0"]
 openai = ["openai>=1.0.0"]
 ollama = ["requests>=2.28.0"]
 ai = ["sentence-transformers>=2.2.0", "anthropic>=0.18.0"]
 
-# Protocols
+# Server & Interfaces
 mcp = ["mcp[cli]>=1.2.0"]
 cli = ["mcp[cli]>=1.2.0"]
+server = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
+dashboard = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
 
-# Infrastructure
+# Storage Backends
 postgres = ["asyncpg>=0.29.0"]
 redis = ["redis>=5.0.0"]
+
+# Infrastructure
 security = ["cryptography>=42.0.0"]
 sync = ["websockets>=12.0"]
 connectors = ["httpx>=0.27.0"]
 
-# Server & Dashboard
-server = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
-dashboard = ["fastapi>=0.110.0", "uvicorn>=0.29.0"]
-
-# Billing (Monetization Phase 2)
-billing = ["stripe>=7.0.0", "httpx>=0.27.0", "asyncpg>=0.29.0"]
-
 # Adapters
 adapters = ["langchain-core>=0.1.0"]
 
-# Full install
+# Full install (everything except billing - removed in v3.0)
 full = [
     "sentence-transformers>=2.2.0", "anthropic>=0.18.0", "openai>=1.0.0",
     "requests>=2.28.0", "mcp[cli]>=1.2.0",
@@ -65,11 +62,10 @@ full = [
     "websockets>=12.0", "httpx>=0.27.0",
     "fastapi>=0.110.0", "uvicorn>=0.29.0",
     "langchain-core>=0.1.0",
-    "stripe>=7.0.0",
 ]
 
+# Development
 docs = ["mkdocs-material>=9.5.0"]
-
 dev = ["pytest>=7.0", "pytest-cov>=4.0", "httpx>=0.27.0"]
 
 [tool.setuptools.packages.find]

stellar_memory-3.0.0/stellar_memory/__init__.py

@@ -0,0 +1,176 @@
+"""Stellar Memory - AI Memory Platform SDK.
+
+Give any AI human-like memory, built on a celestial structure.
+
+v3.0: Clean SDK with 11 core exports. For v2.0 imports, use stellar_memory.compat.
+"""
+
+# 1. Main Class
+from stellar_memory.stellar import StellarMemory
+
+# 2. Builder
+from stellar_memory.builder import StellarBuilder, Preset
+
+# 3. Core Models
+from stellar_memory.models import MemoryItem, MemoryStats
+
+# 4. Plugin Interface
+from stellar_memory.plugin import MemoryPlugin
+
+# 5. Extension Protocols
+from stellar_memory.protocols import (
+    StorageBackendProtocol,
+    EmbedderProvider,
+    ImportanceEvaluator,
+    MemoryStore,
+)
+
+# 6. Config
+from stellar_memory.config import StellarConfig
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("stellar-memory")
+except Exception:
+    __version__ = "3.0.0"
+
+__all__ = [
+    # Main
+    "StellarMemory",
+    # Builder
+    "StellarBuilder",
+    "Preset",
+    # Models
+    "MemoryItem",
+    "MemoryStats",
+    # Plugin
+    "MemoryPlugin",
+    # Protocols
+    "StorageBackendProtocol",
+    "EmbedderProvider",
+    "ImportanceEvaluator",
+    "MemoryStore",
+    # Config
+    "StellarConfig",
+]
+
+
+# --- Backward compatibility ---
+# v2.0 imports (e.g., `from stellar_memory import EventBus`) are redirected
+# to their module-level locations with a deprecation warning.
+
+import importlib as _importlib
+import warnings as _warnings
+
+# Lazy-load v2.0 exports with deprecation warnings
+_V2_COMPAT_MAP: dict[str, tuple[str, str]] = {
+    # Config classes
+    "MemoryFunctionConfig": (".config", "MemoryFunctionConfig"),
+    "ZoneConfig": (".config", "ZoneConfig"),
+    "EmbedderConfig": (".config", "EmbedderConfig"),
+    "LLMConfig": (".config", "LLMConfig"),
+    "TunerConfig": (".config", "TunerConfig"),
+    "ConsolidationConfig": (".config", "ConsolidationConfig"),
+    "SessionConfig": (".config", "SessionConfig"),
+    "NamespaceConfig": (".config", "NamespaceConfig"),
+    "GraphConfig": (".config", "GraphConfig"),
+    "DecayConfig": (".config", "DecayConfig"),
+    "EventLoggerConfig": (".config", "EventLoggerConfig"),
+    "RecallConfig": (".config", "RecallConfig"),
+    "VectorIndexConfig": (".config", "VectorIndexConfig"),
+    "SummarizationConfig": (".config", "SummarizationConfig"),
+    "AdaptiveDecayConfig": (".config", "AdaptiveDecayConfig"),
+    "GraphAnalyticsConfig": (".config", "GraphAnalyticsConfig"),
+    "StorageConfig": (".config", "StorageConfig"),
+    "SyncConfig": (".config", "SyncConfig"),
+    "SecurityConfig": (".config", "SecurityConfig"),
+    "ConnectorConfig": (".config", "ConnectorConfig"),
+    "DashboardConfig": (".config", "DashboardConfig"),
+    "EmotionConfig": (".config", "EmotionConfig"),
+    "ServerConfig": (".config", "ServerConfig"),
+    "MetacognitionConfig": (".config", "MetacognitionConfig"),
+    "SelfLearningConfig": (".config", "SelfLearningConfig"),
+    "MultimodalConfig": (".config", "MultimodalConfig"),
+    "ReasoningConfig": (".config", "ReasoningConfig"),
+    "BenchmarkConfig": (".config", "BenchmarkConfig"),
+    # Removed in v3.0 (redirect to compat for error messages)
+    # "BillingConfig" removed, "OnboardConfig" removed, "KnowledgeBaseConfig" removed
+    # Models
+    "ScoreBreakdown": (".models", "ScoreBreakdown"),
+    "ReorbitResult": (".models", "ReorbitResult"),
+    "EvaluationResult": (".models", "EvaluationResult"),
+    "FeedbackRecord": (".models", "FeedbackRecord"),
+    "ConsolidationResult": (".models", "ConsolidationResult"),
+    "SessionInfo": (".models", "SessionInfo"),
+    "MemorySnapshot": (".models", "MemorySnapshot"),
+    "MemoryEdge": (".models", "MemoryEdge"),
+    "DecayResult": (".models", "DecayResult"),
+    "HealthStatus": (".models", "HealthStatus"),
+    "SummarizationResult": (".models", "SummarizationResult"),
+    "ChangeEvent": (".models", "ChangeEvent"),
+    "AccessRole": (".models", "AccessRole"),
+    "IngestResult": (".models", "IngestResult"),
+    "ZoneDistribution": (".models", "ZoneDistribution"),
+    "EmotionVector": (".models", "EmotionVector"),
+    "TimelineEntry": (".models", "TimelineEntry"),
+    "IntrospectionResult": (".models", "IntrospectionResult"),
+    "ConfidentRecall": (".models", "ConfidentRecall"),
+    "RecallLog": (".models", "RecallLog"),
+    "OptimizationReport": (".models", "OptimizationReport"),
+    "ReasoningResult": (".models", "ReasoningResult"),
+    "Contradiction": (".models", "Contradiction"),
+    "BenchmarkReport": (".models", "BenchmarkReport"),
+    # Core classes
+    "EventBus": (".event_bus", "EventBus"),
+    "MemoryGraph": (".memory_graph", "MemoryGraph"),
+    "PersistentMemoryGraph": (".persistent_graph", "PersistentMemoryGraph"),
+    "NamespaceManager": (".namespace", "NamespaceManager"),
+    "DecayManager": (".decay_manager", "DecayManager"),
+    "EventLogger": (".event_logger", "EventLogger"),
+    "MemoryMiddleware": (".llm_adapter", "MemoryMiddleware"),
+    "AnthropicAdapter": (".llm_adapter", "AnthropicAdapter"),
+    "VectorIndex": (".vector_index", "VectorIndex"),
+    "BruteForceIndex": (".vector_index", "BruteForceIndex"),
+    "BallTreeIndex": (".vector_index", "BallTreeIndex"),
+    "MemorySummarizer": (".summarizer", "MemorySummarizer"),
+    "AdaptiveDecayManager": (".adaptive_decay", "AdaptiveDecayManager"),
+    "GraphAnalyzer": (".graph_analyzer", "GraphAnalyzer"),
+    "GraphStats": (".graph_analyzer", "GraphStats"),
+    "CentralityResult": (".graph_analyzer", "CentralityResult"),
+    "ProviderRegistry": (".providers", "ProviderRegistry"),
+    "StorageBackend": (".storage", "StorageBackend"),
+    "EncryptionManager": (".security.encryption", "EncryptionManager"),
+    "AccessControl": (".security.access_control", "AccessControl"),
+    "SecurityAudit": (".security.audit", "SecurityAudit"),
+    "MemorySyncManager": (".sync", "MemorySyncManager"),
+    "EmotionAnalyzer": (".emotion", "EmotionAnalyzer"),
+    "MemoryStream": (".stream", "MemoryStream"),
+    "Introspector": (".metacognition", "Introspector"),
+    "ConfidenceScorer": (".metacognition", "ConfidenceScorer"),
+    "ContentTypeHandler": (".multimodal", "ContentTypeHandler"),
+    "TextHandler": (".multimodal", "TextHandler"),
+    "CodeHandler": (".multimodal", "CodeHandler"),
+    "JsonHandler": (".multimodal", "JsonHandler"),
+    "get_handler": (".multimodal", "get_handler"),
+    "detect_content_type": (".multimodal", "detect_content_type"),
+    "PatternCollector": (".self_learning", "PatternCollector"),
+    "WeightOptimizer": (".self_learning", "WeightOptimizer"),
+    "MemoryReasoner": (".reasoning", "MemoryReasoner"),
+    "ContradictionDetector": (".reasoning", "ContradictionDetector"),
+    "StandardDataset": (".benchmark", "StandardDataset"),
+    "MemoryBenchmark": (".benchmark", "MemoryBenchmark"),
+}
+
+
+def __getattr__(name: str):
+    if name in _V2_COMPAT_MAP:
+        module_path, attr = _V2_COMPAT_MAP[name]
+        _warnings.warn(
+            f"Importing '{name}' from stellar_memory is deprecated in v3.0. "
+            f"Use 'from stellar_memory{module_path} import {attr}' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        module = _importlib.import_module(module_path, package="stellar_memory")
+        return getattr(module, attr)
+    raise AttributeError(f"module 'stellar_memory' has no attribute {name}")

stellar_memory-3.0.0/stellar_memory/_plugin_manager.py

@@ -0,0 +1,105 @@
+"""Internal plugin manager for dispatching lifecycle hooks."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from stellar_memory.models import MemoryItem
+    from stellar_memory.plugin import MemoryPlugin
+    from stellar_memory.stellar import StellarMemory
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """Manages registered plugins and dispatches hooks."""
+
+    def __init__(self):
+        self._plugins: list[MemoryPlugin] = []
+
+    @property
+    def plugins(self) -> list[MemoryPlugin]:
+        return list(self._plugins)
+
+    def register(self, plugin: MemoryPlugin, memory: StellarMemory) -> None:
+        """Register a plugin and call on_init."""
+        self._plugins.append(plugin)
+        try:
+            plugin.on_init(memory)
+        except Exception:
+            logger.warning("Plugin %s.on_init failed", plugin.name, exc_info=True)
+
+    def dispatch_store(self, item: MemoryItem) -> MemoryItem:
+        """Chain on_store through all plugins."""
+        for plugin in self._plugins:
+            try:
+                item = plugin.on_store(item)
+            except Exception:
+                logger.warning("Plugin %s.on_store failed", plugin.name, exc_info=True)
+        return item
+
+    def dispatch_pre_recall(self, query: str, **kwargs) -> str:
+        """Chain on_pre_recall through all plugins."""
+        for plugin in self._plugins:
+            try:
+                query = plugin.on_pre_recall(query, **kwargs)
+            except Exception:
+                logger.warning("Plugin %s.on_pre_recall failed", plugin.name, exc_info=True)
+        return query
+
+    def dispatch_recall(self, query: str,
+                        results: list[MemoryItem]) -> list[MemoryItem]:
+        """Chain on_recall through all plugins."""
+        for plugin in self._plugins:
+            try:
+                results = plugin.on_recall(query, results)
+            except Exception:
+                logger.warning("Plugin %s.on_recall failed", plugin.name, exc_info=True)
+        return results
+
+    def dispatch_decay(self, item: MemoryItem, score: float) -> float:
+        """Chain on_decay through all plugins."""
+        for plugin in self._plugins:
+            try:
+                score = plugin.on_decay(item, score)
+            except Exception:
+                logger.warning("Plugin %s.on_decay failed", plugin.name, exc_info=True)
+        return score
+
+    def dispatch_reorbit(self, moves: list[tuple[str, int, int]]) -> None:
+        """Notify all plugins of reorbit."""
+        for plugin in self._plugins:
+            try:
+                plugin.on_reorbit(moves)
+            except Exception:
+                logger.warning("Plugin %s.on_reorbit failed", plugin.name, exc_info=True)
+
+    def dispatch_forget(self, memory_id: str) -> bool:
+        """Check all plugins allow forget. Any False cancels."""
+        for plugin in self._plugins:
+            try:
+                if not plugin.on_forget(memory_id):
+                    return False
+            except Exception:
+                logger.warning("Plugin %s.on_forget failed", plugin.name, exc_info=True)
+        return True
+
+    def dispatch_consolidate(self, merged: MemoryItem,
+                             sources: list[MemoryItem]) -> MemoryItem:
+        """Chain on_consolidate through all plugins."""
+        for plugin in self._plugins:
+            try:
+                merged = plugin.on_consolidate(merged, sources)
+            except Exception:
+                logger.warning("Plugin %s.on_consolidate failed", plugin.name, exc_info=True)
+        return merged
+
+    def shutdown(self) -> None:
+        """Call on_shutdown for all plugins."""
+        for plugin in self._plugins:
+            try:
+                plugin.on_shutdown()
+            except Exception:
+                logger.warning("Plugin %s.on_shutdown failed", plugin.name, exc_info=True)