neural-memory 0.1.0__py3-none-any.whl

neural_memory/core/brain.py

@@ -0,0 +1,301 @@
+"""Brain container - the top-level memory structure."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass(frozen=True)
+class BrainConfig:
+    """
+    Configuration for brain behavior.
+
+    Attributes:
+        decay_rate: Rate at which neuron activation decays (per day)
+        reinforcement_delta: Amount to increase synapse weight on access
+        activation_threshold: Minimum activation level to consider active
+        max_spread_hops: Maximum hops in spreading activation
+        max_context_tokens: Maximum tokens to include in context injection
+        default_synapse_weight: Default weight for new synapses
+    """
+
+    decay_rate: float = 0.1
+    reinforcement_delta: float = 0.05
+    activation_threshold: float = 0.2
+    max_spread_hops: int = 4
+    max_context_tokens: int = 1500
+    default_synapse_weight: float = 0.5
+
+    def with_updates(self, **kwargs: Any) -> BrainConfig:
+        """Create a new config with updated values."""
+        return BrainConfig(
+            decay_rate=kwargs.get("decay_rate", self.decay_rate),
+            reinforcement_delta=kwargs.get("reinforcement_delta", self.reinforcement_delta),
+            activation_threshold=kwargs.get("activation_threshold", self.activation_threshold),
+            max_spread_hops=kwargs.get("max_spread_hops", self.max_spread_hops),
+            max_context_tokens=kwargs.get("max_context_tokens", self.max_context_tokens),
+            default_synapse_weight=kwargs.get(
+                "default_synapse_weight", self.default_synapse_weight
+            ),
+        )
+
+
+@dataclass
+class Brain:
+    """
+    A Brain is the top-level container for a memory system.
+
+    It holds configuration, ownership, and statistics for a
+    collection of neurons, synapses, and fibers.
+
+    Attributes:
+        id: Unique identifier
+        name: Human-readable name
+        config: Brain configuration settings
+        owner_id: Optional owner identifier
+        is_public: Whether this brain can be read by anyone
+        shared_with: List of user IDs with access
+        neuron_count: Number of neurons (computed)
+        synapse_count: Number of synapses (computed)
+        fiber_count: Number of fibers (computed)
+        metadata: Additional brain-specific data
+        created_at: When this brain was created
+        updated_at: When this brain was last modified
+    """
+
+    id: str
+    name: str
+    config: BrainConfig = field(default_factory=BrainConfig)
+    owner_id: str | None = None
+    is_public: bool = False
+    shared_with: list[str] = field(default_factory=list)
+    neuron_count: int = 0
+    synapse_count: int = 0
+    fiber_count: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        config: BrainConfig | None = None,
+        owner_id: str | None = None,
+        is_public: bool = False,
+        brain_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Brain:
+        """
+        Factory method to create a new Brain.
+
+        Args:
+            name: Human-readable name
+            config: Optional configuration (uses defaults if None)
+            owner_id: Optional owner identifier
+            is_public: Whether publicly accessible
+            brain_id: Optional explicit ID
+            metadata: Optional metadata
+
+        Returns:
+            A new Brain instance
+        """
+        return cls(
+            id=brain_id or str(uuid4()),
+            name=name,
+            config=config or BrainConfig(),
+            owner_id=owner_id,
+            is_public=is_public,
+            metadata=metadata or {},
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow(),
+        )
+
+    def share_with(self, user_id: str) -> Brain:
+        """
+        Create a new Brain shared with an additional user.
+
+        Args:
+            user_id: User ID to share with
+
+        Returns:
+            New Brain with updated shared_with list
+        """
+        if user_id in self.shared_with:
+            return self
+
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=self.config,
+            owner_id=self.owner_id,
+            is_public=self.is_public,
+            shared_with=[*self.shared_with, user_id],
+            neuron_count=self.neuron_count,
+            synapse_count=self.synapse_count,
+            fiber_count=self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def unshare_with(self, user_id: str) -> Brain:
+        """
+        Create a new Brain with a user removed from sharing.
+
+        Args:
+            user_id: User ID to remove
+
+        Returns:
+            New Brain with updated shared_with list
+        """
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=self.config,
+            owner_id=self.owner_id,
+            is_public=self.is_public,
+            shared_with=[uid for uid in self.shared_with if uid != user_id],
+            neuron_count=self.neuron_count,
+            synapse_count=self.synapse_count,
+            fiber_count=self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def make_public(self) -> Brain:
+        """Create a new Brain that is publicly accessible."""
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=self.config,
+            owner_id=self.owner_id,
+            is_public=True,
+            shared_with=self.shared_with,
+            neuron_count=self.neuron_count,
+            synapse_count=self.synapse_count,
+            fiber_count=self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def make_private(self) -> Brain:
+        """Create a new Brain that is private."""
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=self.config,
+            owner_id=self.owner_id,
+            is_public=False,
+            shared_with=self.shared_with,
+            neuron_count=self.neuron_count,
+            synapse_count=self.synapse_count,
+            fiber_count=self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def with_config(self, config: BrainConfig) -> Brain:
+        """Create a new Brain with updated configuration."""
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=config,
+            owner_id=self.owner_id,
+            is_public=self.is_public,
+            shared_with=self.shared_with,
+            neuron_count=self.neuron_count,
+            synapse_count=self.synapse_count,
+            fiber_count=self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def with_stats(
+        self,
+        neuron_count: int | None = None,
+        synapse_count: int | None = None,
+        fiber_count: int | None = None,
+    ) -> Brain:
+        """Create a new Brain with updated statistics."""
+        return Brain(
+            id=self.id,
+            name=self.name,
+            config=self.config,
+            owner_id=self.owner_id,
+            is_public=self.is_public,
+            shared_with=self.shared_with,
+            neuron_count=neuron_count if neuron_count is not None else self.neuron_count,
+            synapse_count=synapse_count if synapse_count is not None else self.synapse_count,
+            fiber_count=fiber_count if fiber_count is not None else self.fiber_count,
+            metadata=self.metadata,
+            created_at=self.created_at,
+            updated_at=datetime.utcnow(),
+        )
+
+    def can_access(self, user_id: str | None) -> bool:
+        """
+        Check if a user can access this brain.
+
+        Args:
+            user_id: User ID to check (None for anonymous)
+
+        Returns:
+            True if user has access
+        """
+        if self.is_public:
+            return True
+        if user_id is None:
+            return False
+        if self.owner_id == user_id:
+            return True
+        return user_id in self.shared_with
+
+    def can_write(self, user_id: str | None) -> bool:
+        """
+        Check if a user can write to this brain.
+
+        Args:
+            user_id: User ID to check (None for anonymous)
+
+        Returns:
+            True if user has write access
+        """
+        if user_id is None:
+            return False
+        return self.owner_id == user_id
+
+
+@dataclass
+class BrainSnapshot:
+    """
+    A serializable snapshot of a brain for export/import.
+
+    Attributes:
+        brain_id: ID of the original brain
+        brain_name: Name of the brain
+        exported_at: When this snapshot was created
+        version: Schema version for compatibility
+        neurons: List of serialized neurons
+        synapses: List of serialized synapses
+        fibers: List of serialized fibers
+        config: Brain configuration
+        metadata: Additional export metadata
+    """
+
+    brain_id: str
+    brain_name: str
+    exported_at: datetime
+    version: str
+    neurons: list[dict[str, Any]]
+    synapses: list[dict[str, Any]]
+    fibers: list[dict[str, Any]]
+    config: dict[str, Any]
+    metadata: dict[str, Any] = field(default_factory=dict)

neural_memory/core/brain_mode.py

@@ -0,0 +1,273 @@
+"""Brain mode configuration for local/shared storage toggle."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class BrainMode(StrEnum):
+    """Brain storage mode."""
+
+    LOCAL = "local"
+    """Store memories locally only (SQLite or in-memory)."""
+
+    SHARED = "shared"
+    """Connect to remote NeuralMemory server for real-time sharing."""
+
+    HYBRID = "hybrid"
+    """Write locally, sync to server periodically (offline-first)."""
+
+
+class SyncStrategy(StrEnum):
+    """Synchronization strategy for hybrid mode."""
+
+    PUSH_ONLY = "push_only"
+    """Only push local changes to server."""
+
+    PULL_ONLY = "pull_only"
+    """Only pull changes from server."""
+
+    BIDIRECTIONAL = "bidirectional"
+    """Full two-way sync."""
+
+    ON_DEMAND = "on_demand"
+    """Manual sync only."""
+
+
+@dataclass(frozen=True)
+class SharedConfig:
+    """Configuration for shared storage mode."""
+
+    server_url: str
+    """URL of NeuralMemory server (e.g., http://localhost:8000)."""
+
+    api_key: str | None = None
+    """Optional API key for authentication."""
+
+    timeout: float = 30.0
+    """Request timeout in seconds."""
+
+    retry_count: int = 3
+    """Number of retries on connection failure."""
+
+    retry_delay: float = 1.0
+    """Delay between retries in seconds."""
+
+    def with_server_url(self, url: str) -> SharedConfig:
+        """Create new config with different server URL."""
+        return SharedConfig(
+            server_url=url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+            retry_count=self.retry_count,
+            retry_delay=self.retry_delay,
+        )
+
+    def with_api_key(self, key: str | None) -> SharedConfig:
+        """Create new config with different API key."""
+        return SharedConfig(
+            server_url=self.server_url,
+            api_key=key,
+            timeout=self.timeout,
+            retry_count=self.retry_count,
+            retry_delay=self.retry_delay,
+        )
+
+
+@dataclass(frozen=True)
+class HybridConfig:
+    """Configuration for hybrid mode (offline-first with sync)."""
+
+    local_path: str
+    """Path to local SQLite database."""
+
+    server_url: str
+    """URL of NeuralMemory server for sync."""
+
+    api_key: str | None = None
+    """Optional API key for authentication."""
+
+    sync_strategy: SyncStrategy = SyncStrategy.BIDIRECTIONAL
+    """How to synchronize with server."""
+
+    sync_interval_seconds: int = 60
+    """How often to sync (0 = only manual)."""
+
+    auto_sync_on_encode: bool = True
+    """Automatically push new memories to server."""
+
+    auto_sync_on_query: bool = False
+    """Pull from server before queries."""
+
+    conflict_resolution: str = "prefer_local"
+    """How to resolve conflicts: 'prefer_local', 'prefer_remote', 'prefer_recent'."""
+
+
+@dataclass(frozen=True)
+class BrainModeConfig:
+    """
+    Configuration for brain storage mode.
+
+    Determines how memories are stored and shared.
+
+    Examples:
+        # Local-only mode (default)
+        config = BrainModeConfig(mode=BrainMode.LOCAL)
+
+        # Shared mode - connect to server
+        config = BrainModeConfig(
+            mode=BrainMode.SHARED,
+            shared=SharedConfig(server_url="http://localhost:8000"),
+        )
+
+        # Hybrid mode - offline-first with sync
+        config = BrainModeConfig(
+            mode=BrainMode.HYBRID,
+            hybrid=HybridConfig(
+                local_path="./brain.db",
+                server_url="http://localhost:8000",
+                sync_interval_seconds=300,
+            ),
+        )
+    """
+
+    mode: BrainMode = BrainMode.LOCAL
+    """Current storage mode."""
+
+    shared: SharedConfig | None = None
+    """Configuration for shared mode."""
+
+    hybrid: HybridConfig | None = None
+    """Configuration for hybrid mode."""
+
+    @classmethod
+    def local(cls) -> BrainModeConfig:
+        """Create local-only configuration."""
+        return cls(mode=BrainMode.LOCAL)
+
+    @classmethod
+    def shared_mode(
+        cls,
+        server_url: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+    ) -> BrainModeConfig:
+        """
+        Create shared configuration.
+
+        Args:
+            server_url: URL of NeuralMemory server
+            api_key: Optional API key
+            timeout: Request timeout in seconds
+        """
+        return cls(
+            mode=BrainMode.SHARED,
+            shared=SharedConfig(
+                server_url=server_url,
+                api_key=api_key,
+                timeout=timeout,
+            ),
+        )
+
+    @classmethod
+    def hybrid_mode(
+        cls,
+        local_path: str,
+        server_url: str,
+        api_key: str | None = None,
+        sync_interval: int = 60,
+        strategy: SyncStrategy = SyncStrategy.BIDIRECTIONAL,
+    ) -> BrainModeConfig:
+        """
+        Create hybrid (offline-first) configuration.
+
+        Args:
+            local_path: Path to local SQLite database
+            server_url: URL of NeuralMemory server
+            api_key: Optional API key
+            sync_interval: Sync interval in seconds (0 = manual only)
+            strategy: Synchronization strategy
+        """
+        return cls(
+            mode=BrainMode.HYBRID,
+            hybrid=HybridConfig(
+                local_path=local_path,
+                server_url=server_url,
+                api_key=api_key,
+                sync_strategy=strategy,
+                sync_interval_seconds=sync_interval,
+            ),
+        )
+
+    def is_local(self) -> bool:
+        """Check if using local-only mode."""
+        return self.mode == BrainMode.LOCAL
+
+    def is_shared(self) -> bool:
+        """Check if using shared (remote) mode."""
+        return self.mode == BrainMode.SHARED
+
+    def is_hybrid(self) -> bool:
+        """Check if using hybrid (offline-first) mode."""
+        return self.mode == BrainMode.HYBRID
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        result: dict[str, Any] = {"mode": self.mode.value}
+
+        if self.shared:
+            result["shared"] = {
+                "server_url": self.shared.server_url,
+                "api_key": self.shared.api_key,
+                "timeout": self.shared.timeout,
+                "retry_count": self.shared.retry_count,
+                "retry_delay": self.shared.retry_delay,
+            }
+
+        if self.hybrid:
+            result["hybrid"] = {
+                "local_path": self.hybrid.local_path,
+                "server_url": self.hybrid.server_url,
+                "api_key": self.hybrid.api_key,
+                "sync_strategy": self.hybrid.sync_strategy.value,
+                "sync_interval_seconds": self.hybrid.sync_interval_seconds,
+                "auto_sync_on_encode": self.hybrid.auto_sync_on_encode,
+                "auto_sync_on_query": self.hybrid.auto_sync_on_query,
+                "conflict_resolution": self.hybrid.conflict_resolution,
+            }
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BrainModeConfig:
+        """Create from dictionary."""
+        mode = BrainMode(data.get("mode", "local"))
+
+        shared = None
+        if "shared" in data:
+            s = data["shared"]
+            shared = SharedConfig(
+                server_url=s["server_url"],
+                api_key=s.get("api_key"),
+                timeout=s.get("timeout", 30.0),
+                retry_count=s.get("retry_count", 3),
+                retry_delay=s.get("retry_delay", 1.0),
+            )
+
+        hybrid = None
+        if "hybrid" in data:
+            h = data["hybrid"]
+            hybrid = HybridConfig(
+                local_path=h["local_path"],
+                server_url=h["server_url"],
+                api_key=h.get("api_key"),
+                sync_strategy=SyncStrategy(h.get("sync_strategy", "bidirectional")),
+                sync_interval_seconds=h.get("sync_interval_seconds", 60),
+                auto_sync_on_encode=h.get("auto_sync_on_encode", True),
+                auto_sync_on_query=h.get("auto_sync_on_query", False),
+                conflict_resolution=h.get("conflict_resolution", "prefer_local"),
+            )
+
+        return cls(mode=mode, shared=shared, hybrid=hybrid)