memplex 3.2.0__py3-none-any.whl

memnex/storage/__init__.py

@@ -0,0 +1,65 @@
+"""MemNex storage layer -- MemoryStore interface and backends."""
+
+from memnex.storage.base import MemoryStore
+from memnex.storage.lite.store import LiteMemoryStore
+from memnex.storage.changelog import ChangelogStore
+from memnex.storage.vector import (
+    VectorStore,
+    InMemoryVectorStore,
+    ChromaVectorStore,
+    create_vector_store,
+)
+from memnex.storage.feedback import (
+    FeedbackStore,
+    LiteFeedbackStore,
+    SQLiteFeedbackStore,
+    PostgresFeedbackStore,
+    create_feedback_store,
+)
+
+from typing import Optional
+
+
+def create_store(
+    config=None,
+    **kwargs,
+) -> MemoryStore:
+    """Factory: create a MemoryStore.
+
+    Accepts either a MemNexConfig object or a backend string.
+    Falls back to 'lite' for unsupported backends.
+    """
+    if config is not None and hasattr(config, 'storage'):
+        backend = config.storage.backend
+        storage_path = config.storage.path
+    else:
+        backend = config if isinstance(config, str) else kwargs.get('backend', 'lite')
+        storage_path = kwargs.get('path')
+
+    if backend in ("lite", "standard", "enterprise"):
+        from pathlib import Path
+        path = Path(storage_path).expanduser() / "memory.json" if storage_path else None
+        try:
+            return LiteMemoryStore(path=path)
+        except Exception:
+            return LiteMemoryStore()
+    raise ValueError(
+        f"Unknown storage backend: {backend!r}. Supported: 'lite'."
+    )
+
+
+__all__ = [
+    "MemoryStore",
+    "LiteMemoryStore",
+    "ChangelogStore",
+    "VectorStore",
+    "InMemoryVectorStore",
+    "ChromaVectorStore",
+    "create_vector_store",
+    "FeedbackStore",
+    "LiteFeedbackStore",
+    "SQLiteFeedbackStore",
+    "PostgresFeedbackStore",
+    "create_feedback_store",
+    "create_store",
+]

memnex/storage/base.py

@@ -0,0 +1,132 @@
+"""MemoryStore abstract base class -- unified data access layer.
+
+Pure CRUD + basic retrieval.  No orchestration logic (that belongs in
+MemNexService).  Every concrete backend (Lite, Standard, Enterprise)
+implements this interface.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from memnex.models import (
+    BatchResult,
+    ChangelogEvent,
+    Function,
+    GraphData,
+    MergeResult,
+    Observation,
+    SearchFilters,
+    SearchResult,
+    SourceDocument,
+)
+
+
+class MemoryStore(ABC):
+    """Pure data access layer -- CRUD + basic retrieval, no orchestration."""
+
+    # ── Write operations ────────────────────────────────────────────
+
+    @abstractmethod
+    def add(self, func: Function, source: SourceDocument) -> None:
+        """Add a Function.  If a Function with the same *name_normalized*
+        already exists, its FieldValues are merged instead.
+
+        Concurrency (Lite backend): single-threaded, optimistic lock skipped.
+        """
+
+    @abstractmethod
+    def add_batch(
+        self,
+        funcs: List[Function],
+        sources: List[SourceDocument],
+    ) -> BatchResult:
+        """Batch add.  Calls :meth:`add` per item; single-item failure does
+        **not** abort the rest.  Failed items are recorded in
+        ``BatchResult.failed_items``.
+        """
+
+    @abstractmethod
+    def add_observation(self, observation: Observation) -> None:
+        """Persist an Observation event."""
+
+    @abstractmethod
+    def increment_access(self, func_id: str) -> None:
+        """Atomically increment ``access_count`` and update
+        ``last_accessed_at``.  Must not depend on a prior ``get()`` to
+        avoid read-modify-write races.
+        """
+
+    # ── Retrieval ───────────────────────────────────────────────────
+
+    @abstractmethod
+    def vector_search(self, text: str, top_k: int = 5) -> List[SearchResult]:
+        """Semantic / vector similarity search."""
+
+    @abstractmethod
+    def fts_search(self, text: str, top_k: int = 10) -> List[SearchResult]:
+        """Full-text / keyword search."""
+
+    @abstractmethod
+    def filter(self, filters: SearchFilters) -> List[Function]:
+        """Structured filter over stored Functions."""
+
+    # ── Read operations ─────────────────────────────────────────────
+
+    @abstractmethod
+    def get(self, func_id: str) -> Optional[Function]:
+        """Retrieve a single Function by ID, or ``None``."""
+
+    @abstractmethod
+    def get_neighbors(
+        self,
+        func_id: str,
+        edge_types: Optional[List[str]] = None,
+        max_hops: int = 1,
+    ) -> List[Function]:
+        """Return neighbour Functions reachable within *max_hops* edges,
+        optionally restricted to *edge_types*.
+        """
+
+    @abstractmethod
+    def get_graph(
+        self,
+        func_ids: Optional[List[str]] = None,
+    ) -> GraphData:
+        """Return sub-graph.  If *func_ids* is ``None`` the full graph is
+        returned.
+        """
+
+    @abstractmethod
+    def get_timeline(
+        self,
+        func_id: str,
+        limit: int = 20,
+    ) -> List[ChangelogEvent]:
+        """Return recent ChangelogEvents for a Function."""
+
+    @abstractmethod
+    def list_functions(
+        self,
+        offset: int = 0,
+        limit: int = 1000,
+        owner: Optional[str] = None,
+    ) -> List[Function]:
+        """Paginated listing, optionally filtered by *owner*."""
+
+    # ── Delete / merge / clear ──────────────────────────────────────
+
+    @abstractmethod
+    def delete(self, func_id: str) -> None:
+        """Soft-delete a Function and its associated graph edges."""
+
+    @abstractmethod
+    def merge(self, sub_graph: GraphData) -> MergeResult:
+        """Incrementally fuse *sub_graph* into the main graph.  Existing
+        nodes are merged; new ones are inserted.
+        """
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all stored data (Functions, edges, changelog)."""

memnex/storage/changelog.py

@@ -0,0 +1,106 @@
+"""ChangelogStore -- lightweight append-only event log.
+
+Lite implementation: in-memory list persisted to a JSON file.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from memnex.models import ChangelogEvent
+
+logger = logging.getLogger(__name__)
+
+
+class ChangelogStore:
+    """Append-only changelog with JSON persistence.
+
+    Data path: ``~/.memnex/changelog.json``
+    """
+
+    def __init__(self, path: Optional[Path] = None) -> None:
+        self._path = path or Path("~/.memnex/changelog.json").expanduser()
+        self._events: List[ChangelogEvent] = []
+        self._load()
+
+    # ── Public API ──────────────────────────────────────────────────
+
+    def append(self, event: ChangelogEvent) -> None:
+        """Append an event and persist."""
+        self._events.append(event)
+        self._save()
+
+    def get_timeline(
+        self,
+        func_id: str,
+        limit: int = 20,
+    ) -> List[ChangelogEvent]:
+        """Return the most recent events for *func_id*, newest first."""
+        matching = [e for e in self._events if e.func_id == func_id]
+        matching.sort(key=lambda e: e.timestamp, reverse=True)
+        return matching[:limit]
+
+    def clear(self) -> None:
+        """Remove all events."""
+        self._events.clear()
+        self._save()
+
+    # ── Persistence helpers ─────────────────────────────────────────
+
+    @staticmethod
+    def _serialize_event(event: ChangelogEvent) -> dict:
+        return {
+            "func_id": event.func_id,
+            "timestamp": (
+                event.timestamp.isoformat()
+                if isinstance(event.timestamp, datetime)
+                else event.timestamp
+            ),
+            "event_type": event.event_type,
+            "description": event.description,
+            "source": event.source,
+            "actor": event.actor,
+        }
+
+    @staticmethod
+    def _deserialize_event(data: dict) -> ChangelogEvent:
+        ts = data["timestamp"]
+        if isinstance(ts, str):
+            ts = datetime.fromisoformat(ts)
+        return ChangelogEvent(
+            func_id=data["func_id"],
+            timestamp=ts,
+            event_type=data["event_type"],
+            description=data["description"],
+            source=data["source"],
+            actor=data["actor"],
+        )
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            return
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+            self._events = [self._deserialize_event(d) for d in raw]
+        except Exception:
+            logger.warning("Failed to load changelog from %s", self._path)
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        data = [self._serialize_event(e) for e in self._events]
+        # Atomic write: write to temp then rename
+        tmp_fd, tmp_path = tempfile.mkstemp(
+            dir=str(self._path.parent), suffix=".tmp"
+        )
+        try:
+            with open(tmp_fd, "w", encoding="utf-8") as fh:
+                json.dump(data, fh, ensure_ascii=False, indent=2)
+            Path(tmp_path).replace(self._path)
+        except Exception:
+            Path(tmp_path).unlink(missing_ok=True)
+            raise