neural-memorygraph 1.0.0__py3-none-any.whl

memorygraph/__init__.py

@@ -0,0 +1,142 @@
+"""
+memorygraph
+===========
+Yapay zekalar için grafik tabanlı hafıza sistemi.
+
+Modern Hopfield Ağları, yayılma aktivasyonu, Ebbinghaus unutma eğrisi
+ve differansiyellenebilir hafıza bileşenleri içerir.
+
+Hızlı başlangıç::
+
+    from memorygraph import MemoryGraph, MemoryNode, MemoryEdge
+    from memorygraph import MemoryType, EdgeType
+    from memorygraph import SpacedRepetitionScheduler
+    from memorygraph import SpreadingActivation, SpreadingConfig
+    from memorygraph import WorkingMemoryBuffer
+    from memorygraph import GraphStorageManager
+
+    # Graf oluştur
+    graph = MemoryGraph(embedding_dim=768, name="agent_memory")
+
+    # Düğüm ekle
+    node = MemoryNode(
+        content    = "Python dilini öğrendim",
+        memory_type= MemoryType.EPISODIC,
+        importance = 0.8,
+    )
+    graph.add_node(node)
+
+    # Yayılma aktivasyonu
+    spreader = SpreadingActivation(graph)
+    results  = spreader.spread([node.id])
+
+    # Aralıklı tekrar zamanlayıcısı
+    scheduler = SpacedRepetitionScheduler(model="fsrs")
+    scheduler.register_node(node.id)
+
+    # Kalıcı depolama
+    storage = GraphStorageManager(backend="sqlite")
+    storage.save(graph, "memory.db")
+    graph2 = storage.load("memory.db")
+
+PyTorch modülleri::
+
+    from memorygraph.neural import (
+        ModernHopfieldLayer,
+        HopfieldMemoryPool,
+        HopfieldStack,
+        MemoryEncoder,
+        NeuralMemoryModule,
+        MemoryNetwork,
+    )
+
+    hopfield = ModernHopfieldLayer(input_dim=512, hidden_dim=512, num_heads=8)
+    query    = torch.randn(2, 10, 512)
+    patterns = torch.randn(2, 64, 512)
+    out, attn = hopfield(query, patterns)
+"""
+
+from .core.types import (
+    MemoryType,
+    EdgeType,
+    ConsolidationState,
+    DecayFunction,
+    RetrievalStrategy,
+    ImportanceLevel,
+    RetrievalResult,
+    GraphStats,
+    NodeID,
+    EdgeID,
+    Embedding,
+    # Exceptions
+    MemoryGraphError,
+    NodeNotFoundError,
+    EdgeNotFoundError,
+    EmbeddingDimensionError,
+    WorkingMemoryCapacityError,
+    ConsolidationError,
+)
+
+from .core.node  import MemoryNode, TemporalInfo
+from .core.edge  import MemoryEdge
+from .core.graph import MemoryGraph
+
+from .memory.working import (
+    WorkingMemoryBuffer,
+    WorkingMemoryItem,
+    WorkingMemorySlot,
+)
+
+from .retrieval.spreading import (
+    SpreadingActivation,
+    SpreadingConfig,
+    ActivationResult,
+)
+
+from .decay.forgetting import (
+    ForgettingModel,
+    EbbinghausModel,
+    PowerLawModel,
+    SM2Model,
+    SM2Card,
+    FSRSModel,
+    SpacedRepetitionScheduler,
+    ReviewScheduleEntry,
+)
+
+from .persistence.storage import (
+    StorageBackend,
+    JSONBackend,
+    PickleBackend,
+    SQLiteBackend,
+    GraphStorageManager,
+)
+
+
+__version__  = "1.0.0"
+__author__   = "memorygraph"
+__license__  = "MIT"
+
+__all__ = [
+    # Core
+    "MemoryGraph", "MemoryNode", "MemoryEdge", "TemporalInfo",
+    # Types & Enums
+    "MemoryType", "EdgeType", "ConsolidationState", "DecayFunction",
+    "RetrievalStrategy", "ImportanceLevel",
+    "RetrievalResult", "GraphStats",
+    "NodeID", "EdgeID", "Embedding",
+    # Exceptions
+    "MemoryGraphError", "NodeNotFoundError", "EdgeNotFoundError",
+    "EmbeddingDimensionError", "WorkingMemoryCapacityError", "ConsolidationError",
+    # Working Memory
+    "WorkingMemoryBuffer", "WorkingMemoryItem", "WorkingMemorySlot",
+    # Retrieval
+    "SpreadingActivation", "SpreadingConfig", "ActivationResult",
+    # Decay & Forgetting
+    "ForgettingModel", "EbbinghausModel", "PowerLawModel",
+    "SM2Model", "SM2Card", "FSRSModel",
+    "SpacedRepetitionScheduler", "ReviewScheduleEntry",
+    # Persistence
+    "StorageBackend", "JSONBackend", "PickleBackend",
+    "SQLiteBackend", "GraphStorageManager",
+]

memorygraph/core/__init__.py

@@ -0,0 +1,4 @@
+from .types import *
+from .node  import MemoryNode, TemporalInfo
+from .edge  import MemoryEdge
+from .graph import MemoryGraph

memorygraph/core/edge.py

@@ -0,0 +1,219 @@
+"""
+memorygraph.core.edge
+=====================
+MemoryEdge — iki hafıza düğümü arasındaki ilişki.
+
+Kenarlar yönlü veya yönsüz olabilir, ağırlık taşır ve
+zamansal meta veriye sahiptir.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from .types import EdgeID, EdgeType, Metadata, NodeID
+
+
+class MemoryEdge:
+    """
+    Hafıza düğümleri arasındaki ilişkiyi modelleyen kenar.
+
+    Özellikler:
+    - **Ağırlık**: ilişkinin güçü (0-1 arası, öğrenilebilir)
+    - **Yön**: kaynak → hedef (yönsüz graflar için iki yönlü kenar)
+    - **Tür**: semantik ilişki kategorisi (causal, temporal, vb.)
+    - **Güven**: bu ilişkiye duyulan güven düzeyi
+    - **Zamansal**: ne zaman oluşturuldu/güncellendi
+    """
+
+    __slots__ = (
+        "_id", "_source_id", "_target_id", "_edge_type",
+        "_weight", "_confidence", "_directed",
+        "_created_at", "_last_updated", "_update_count",
+        "_metadata",
+    )
+
+    def __init__(
+        self,
+        source_id: NodeID,
+        target_id: NodeID,
+        edge_type: EdgeType = EdgeType.ASSOCIATION,
+        weight: float = 1.0,
+        confidence: float = 1.0,
+        directed: bool = True,
+        metadata: Optional[Metadata] = None,
+        edge_id: Optional[EdgeID] = None,
+    ) -> None:
+        if not (0.0 <= weight <= 1.0):
+            raise ValueError(f"Kenar ağırlığı 0-1 arasında olmalı, alınan: {weight}")
+        if not (0.0 <= confidence <= 1.0):
+            raise ValueError(f"Güven değeri 0-1 arasında olmalı, alınan: {confidence}")
+
+        self._id: EdgeID = edge_id or str(uuid.uuid4())
+        self._source_id: NodeID = source_id
+        self._target_id: NodeID = target_id
+        self._edge_type: EdgeType = edge_type
+        self._weight: float = weight
+        self._confidence: float = confidence
+        self._directed: bool = directed
+        self._created_at: float = time.time()
+        self._last_updated: float = self._created_at
+        self._update_count: int = 0
+        self._metadata: Metadata = dict(metadata or {})
+
+    # -----------------------------------------------------------------------
+    # Özellikler
+    # -----------------------------------------------------------------------
+
+    @property
+    def id(self) -> EdgeID:
+        return self._id
+
+    @property
+    def source_id(self) -> NodeID:
+        return self._source_id
+
+    @property
+    def target_id(self) -> NodeID:
+        return self._target_id
+
+    @property
+    def edge_type(self) -> EdgeType:
+        return self._edge_type
+
+    @property
+    def weight(self) -> float:
+        return self._weight
+
+    @weight.setter
+    def weight(self, value: float) -> None:
+        if not (0.0 <= value <= 1.0):
+            raise ValueError(f"Ağırlık 0-1 arasında olmalı: {value}")
+        self._weight = value
+        self._last_updated = time.time()
+        self._update_count += 1
+
+    @property
+    def confidence(self) -> float:
+        return self._confidence
+
+    @confidence.setter
+    def confidence(self, value: float) -> None:
+        self._confidence = max(0.0, min(1.0, value))
+        self._last_updated = time.time()
+
+    @property
+    def directed(self) -> bool:
+        return self._directed
+
+    @property
+    def effective_weight(self) -> float:
+        """Güvenle ağırlıklandırılmış etkin kenar gücü."""
+        return self._weight * self._confidence
+
+    @property
+    def age_seconds(self) -> float:
+        return time.time() - self._created_at
+
+    @property
+    def metadata(self) -> Metadata:
+        return self._metadata
+
+    def get_other_end(self, node_id: NodeID) -> Optional[NodeID]:
+        """Verilen düğümün diğer ucunu döndürür."""
+        if node_id == self._source_id:
+            return self._target_id
+        if node_id == self._target_id and not self._directed:
+            return self._source_id
+        return None
+
+    def connects(self, a: NodeID, b: NodeID) -> bool:
+        """Bu kenar a ve b'yi bağlıyor mu?"""
+        if self._directed:
+            return self._source_id == a and self._target_id == b
+        return (self._source_id == a and self._target_id == b) or \
+               (self._source_id == b and self._target_id == a)
+
+    # -----------------------------------------------------------------------
+    # Hebbian öğrenme güncellemesi
+    # -----------------------------------------------------------------------
+
+    def hebbian_update(
+        self,
+        delta: float = 0.05,
+        decay: float = 0.01,
+        max_weight: float = 1.0,
+    ) -> None:
+        """
+        Hebbian öğrenme kuralı: "Birlikte ateşlenen nöronlar birbirine bağlanır."
+
+        Δw = δ · (1 - w) - λ · w
+
+        delta: öğrenme oranı
+        decay: ağırlık çürümesi (normalize edici)
+        """
+        dw = delta * (max_weight - self._weight) - decay * self._weight
+        self._weight = float(max(0.0, min(max_weight, self._weight + dw)))
+        self._last_updated = time.time()
+        self._update_count += 1
+
+    def decay_weight(self, rate: float = 0.001) -> None:
+        """Kenar ağırlığını zamanla zayıflat."""
+        self._weight = max(0.0, self._weight * (1.0 - rate))
+        self._last_updated = time.time()
+
+    # -----------------------------------------------------------------------
+    # Serileştirme
+    # -----------------------------------------------------------------------
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id":           self._id,
+            "source_id":    self._source_id,
+            "target_id":    self._target_id,
+            "edge_type":    self._edge_type.value,
+            "weight":       self._weight,
+            "confidence":   self._confidence,
+            "directed":     self._directed,
+            "created_at":   self._created_at,
+            "last_updated": self._last_updated,
+            "update_count": self._update_count,
+            "metadata":     self._metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryEdge":
+        edge = cls(
+            source_id  = data["source_id"],
+            target_id  = data["target_id"],
+            edge_type  = EdgeType(data.get("edge_type", "association")),
+            weight     = data.get("weight", 1.0),
+            confidence = data.get("confidence", 1.0),
+            directed   = data.get("directed", True),
+            metadata   = data.get("metadata", {}),
+            edge_id    = data.get("id"),
+        )
+        edge._created_at   = data.get("created_at",   edge._created_at)
+        edge._last_updated = data.get("last_updated",  edge._last_updated)
+        edge._update_count = data.get("update_count",  0)
+        return edge
+
+    # -----------------------------------------------------------------------
+    # Dunder metodları
+    # -----------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        arrow = "→" if self._directed else "↔"
+        return (
+            f"MemoryEdge('{self._source_id[:8]}' {arrow} '{self._target_id[:8]}', "
+            f"type={self._edge_type.name}, w={self._weight:.3f})"
+        )
+
+    def __hash__(self) -> int:
+        return hash(self._id)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, MemoryEdge) and self._id == other._id