monkeybrain-runtime 1.0.0__py3-none-any.whl

src/monkey_brain/kernel/rl/transition.py

@@ -0,0 +1,112 @@
+"""Transition — RL transition model.
+
+Represents: (state, action, reward, next_state, done)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+import hashlib
+import json
+
+
+@dataclass
+class Transition:
+    """A single transition in the RL model."""
+    
+    transition_id: str = field(default_factory=lambda: f"trans-{uuid4().hex[:8]}")
+    state: dict[str, Any] = field(default_factory=dict)
+    action: str = ""
+    reward: float = 0.0
+    next_state: dict[str, Any] = field(default_factory=dict)
+    done: bool = False
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, eq=True)
+class TransitionKey:
+    """Key for transition table lookup."""
+    
+    state_hash: str
+    action: str
+
+
+def hash_state(state: dict[str, Any]) -> str:
+    """Hash state for table lookup."""
+    state_str = json.dumps(state, sort_keys=True, default=str)
+    return hashlib.md5(state_str.encode()).hexdigest()[:16]
+
+
+class TransitionTable:
+    """Table storing observed transitions.
+    
+    Responsibilities:
+    - Store transitions
+    - Query by state/action
+    - Sample for learning
+    - Evict old entries
+    """
+    
+    def __init__(self, max_size: int = 10000):
+        self._transitions: dict[TransitionKey, list[Transition]] = {}
+        self._max_size = max_size
+        self._count = 0
+    
+    def store(self, transition: Transition) -> None:
+        """Store a transition."""
+        key = TransitionKey(
+            state_hash=hash_state(transition.state),
+            action=transition.action,
+        )
+        if key not in self._transitions:
+            self._transitions[key] = []
+        self._transitions[key].append(transition)
+        self._count += 1
+        
+        if self._count > self._max_size:
+            self._evict()
+    
+    def query(self, state: dict, action: str | None = None) -> list[Transition]:
+        """Query transitions by state and optionally action."""
+        state_hash = hash_state(state)
+        results = []
+        for key, trans in self._transitions.items():
+            if key.state_hash == state_hash:
+                if action is None or key.action == action:
+                    results.extend(trans)
+        return results
+    
+    def sample(self, n: int = 32) -> list[Transition]:
+        """Sample random transitions for learning."""
+        import random
+        all_transitions = []
+        for trans in self._transitions.values():
+            all_transitions.extend(trans)
+        return random.sample(all_transitions, min(n, len(all_transitions)))
+    
+    def get_actions(self, state: dict) -> list[str]:
+        """Get all actions taken in a given state."""
+        state_hash = hash_state(state)
+        actions = set()
+        for key in self._transitions.keys():
+            if key.state_hash == state_hash:
+                actions.add(key.action)
+        return list(actions)
+    
+    def _evict(self) -> None:
+        """Evict oldest transitions."""
+        keys = list(self._transitions.keys())
+        for key in keys[:len(keys)//2]:
+            del self._transitions[key]
+        self._count = sum(len(v) for v in self._transitions.values())
+    
+    def count(self) -> int:
+        return self._count
+    
+    def clear(self) -> None:
+        self._transitions.clear()
+        self._count = 0

src/monkey_brain/persistence/__init__.py

@@ -0,0 +1,47 @@
+"""AgentOS Persistence Layer — first-class runtime subsystem.
+
+Provides:
+- PersistenceManager: single gateway to storage
+- Reducer: pure state mutation
+- Events: immutable persistence events
+- Adapters: store-specific implementations
+
+Every persistence technology owns exactly one responsibility.
+No database duplicates another's responsibility.
+Every write originates from a runtime state transition.
+Reducers own state mutation.
+Persistence layers persist the results of state mutations.
+"""
+
+from src.monkey_brain.persistence.manager import PersistenceManager
+from src.monkey_brain.persistence.reducer import Reducer, StateMutation
+from src.monkey_brain.persistence.events import (
+    PersistenceEvent,
+    EventType,
+    EntityCreated,
+    EntityUpdated,
+    EntityDeleted,
+    RelationshipCreated,
+    MemoryStored,
+    WorkflowStarted,
+    WorkflowCompleted,
+    MetricRecorded,
+)
+from src.monkey_brain.persistence.adapters import IStoreAdapter
+
+__all__ = [
+    "PersistenceManager",
+    "Reducer",
+    "StateMutation",
+    "PersistenceEvent",
+    "EventType",
+    "EntityCreated",
+    "EntityUpdated",
+    "EntityDeleted",
+    "RelationshipCreated",
+    "MemoryStored",
+    "WorkflowStarted",
+    "WorkflowCompleted",
+    "MetricRecorded",
+    "IStoreAdapter",
+]

src/monkey_brain/persistence/adapters.py

@@ -0,0 +1,49 @@
+"""Store Adapters — interface for persistence stores.
+
+Each store adapter implements the same interface.
+The Persistence Manager routes to the appropriate adapter.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class IStoreAdapter(ABC):
+    """Interface for persistence store adapters."""
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Store name (mongodb, neo4j, redis, etc.)."""
+        ...
+    
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to store."""
+        ...
+    
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Close connection to store."""
+        ...
+    
+    @abstractmethod
+    async def health(self) -> dict[str, Any]:
+        """Check store health."""
+        ...
+    
+    @abstractmethod
+    async def persist(self, event: Any) -> dict[str, Any]:
+        """Persist an event to the store."""
+        ...
+    
+    @abstractmethod
+    async def query(self, entity_type: str, entity_id: str | None = None) -> Any:
+        """Query entities from the store."""
+        ...
+    
+    def is_connected(self) -> bool:
+        """Check if store is connected."""
+        return False

src/monkey_brain/persistence/events.py

@@ -0,0 +1,105 @@
+"""Persistence Events — immutable runtime events.
+
+Every persistence operation becomes an event.
+Events are append-only, never updated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+
+class EventType(str, Enum):
+    # Entity events
+    ENTITY_CREATED = "entity.created"
+    ENTITY_UPDATED = "entity.updated"
+    ENTITY_DELETED = "entity.deleted"
+    
+    # Relationship events
+    RELATIONSHIP_CREATED = "relationship.created"
+    RELATIONSHIP_DELETED = "relationship.deleted"
+    
+    # Memory events
+    MEMORY_STORED = "memory.stored"
+    MEMORY_UPDATED = "memory.updated"
+    MEMORY_FORGOTTEN = "memory.forgotten"
+    
+    # Workflow events
+    WORKFLOW_STARTED = "workflow.started"
+    WORKFLOW_COMPLETED = "workflow.completed"
+    WORKFLOW_FAILED = "workflow.failed"
+    
+    # Pipeline events
+    PIPELINE_EXECUTED = "pipeline.executed"
+    CAPABILITY_INVOKED = "capability.invoked"
+    
+    # Session events
+    SESSION_CREATED = "session.created"
+    SESSION_EXPIRED = "session.expired"
+    
+    # Audit events
+    AUDIT_RECORDED = "audit.recorded"
+    
+    # Search events
+    SEARCH_INDEXED = "search.indexed"
+    
+    # Metric events
+    METRIC_RECORDED = "metric.recorded"
+
+
+@dataclass
+class PersistenceEvent:
+    """An immutable persistence event."""
+    
+    event_id: str = field(default_factory=lambda: f"evt-{uuid4().hex[:12]}")
+    event_type: EventType = EventType.ENTITY_CREATED
+    entity_type: str = ""
+    entity_id: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    source: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EntityCreated(PersistenceEvent):
+    event_type: EventType = EventType.ENTITY_CREATED
+
+
+@dataclass
+class EntityUpdated(PersistenceEvent):
+    event_type: EventType = EventType.ENTITY_UPDATED
+
+
+@dataclass
+class EntityDeleted(PersistenceEvent):
+    event_type: EventType = EventType.ENTITY_DELETED
+
+
+@dataclass
+class RelationshipCreated(PersistenceEvent):
+    event_type: EventType = EventType.RELATIONSHIP_CREATED
+
+
+@dataclass
+class MemoryStored(PersistenceEvent):
+    event_type: EventType = EventType.MEMORY_STORED
+
+
+@dataclass
+class WorkflowStarted(PersistenceEvent):
+    event_type: EventType = EventType.WORKFLOW_STARTED
+
+
+@dataclass
+class WorkflowCompleted(PersistenceEvent):
+    event_type: EventType = EventType.WORKFLOW_COMPLETED
+
+
+@dataclass
+class MetricRecorded(PersistenceEvent):
+    event_type: EventType = EventType.METRIC_RECORDED

src/monkey_brain/persistence/manager.py

@@ -0,0 +1,124 @@
+"""Persistence Manager — single gateway to storage.
+
+Routes persistence operations to appropriate stores.
+Handles retries and consistency.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from src.monkey_brain.persistence.adapters import IStoreAdapter
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+from src.monkey_brain.persistence.reducer import Reducer, StateMutation
+
+logger = logging.getLogger(__name__)
+
+
+class PersistenceManager:
+    """Routes persistence operations to appropriate stores.
+    
+    Responsibilities:
+    - Route events to correct store adapters
+    - Handle retries
+    - Guarantee consistency
+    - Publish completion events
+    
+    The Persistence Manager is the single gateway to storage.
+    Runtime components never write directly to databases.
+    """
+    
+    def __init__(self):
+        self._adapters: dict[str, IStoreAdapter] = {}
+        self._reducer = Reducer()
+        self._event_log: list[PersistenceEvent] = []
+    
+    def register_adapter(self, adapter: IStoreAdapter) -> None:
+        """Register a store adapter."""
+        self._adapters[adapter.name] = adapter
+    
+    def get_adapter(self, name: str) -> IStoreAdapter | None:
+        return self._adapters.get(name)
+    
+    async def connect_all(self) -> None:
+        """Connect to all registered stores."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.connect()
+                logger.info(f"Connected to {adapter.name}")
+            except Exception as e:
+                logger.warning(f"Failed to connect to {adapter.name}: {e}")
+    
+    async def disconnect_all(self) -> None:
+        """Disconnect from all stores."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.disconnect()
+            except Exception:
+                pass
+    
+    async def persist(self, event: PersistenceEvent) -> dict[str, Any]:
+        """Persist an event to the appropriate store."""
+        self._event_log.append(event)
+        
+        adapter = self._select_adapter(event)
+        if adapter is None:
+            return {"status": "no_adapter", "event_type": event.event_type}
+        
+        try:
+            result = await adapter.persist(event)
+            logger.debug(f"Persisted {event.event_type} to {adapter.name}")
+            return result
+        except Exception as e:
+            logger.error(f"Failed to persist to {adapter.name}: {e}")
+            return {"status": "error", "error": str(e)}
+    
+    async def apply_mutation(self, mutation: StateMutation) -> dict[str, Any]:
+        """Apply a state mutation with persistence."""
+        results = []
+        for event in mutation.persistence_events:
+            result = await self.persist(event)
+            results.append(result)
+        return {"mutations": len(results), "results": results}
+    
+    async def health(self) -> dict[str, Any]:
+        """Check health of all stores."""
+        health = {}
+        for name, adapter in self._adapters.items():
+            try:
+                health[name] = await adapter.health()
+            except Exception as e:
+                health[name] = {"status": "error", "error": str(e)}
+        return health
+    
+    def _select_adapter(self, event: PersistenceEvent) -> IStoreAdapter | None:
+        """Select appropriate adapter based on event type."""
+        # Entity events → MongoDB
+        if event.event_type in (
+            EventType.ENTITY_CREATED,
+            EventType.ENTITY_UPDATED,
+            EventType.ENTITY_DELETED,
+        ):
+            return self._adapters.get("mongodb")
+        
+        # Memory events → mem0 or Redis
+        if event.event_type in (
+            EventType.MEMORY_STORED,
+            EventType.MEMORY_UPDATED,
+            EventType.MEMORY_FORGOTTEN,
+        ):
+            return self._adapters.get("redis") or self._adapters.get("mem0")
+        
+        # Metric events → InfluxDB
+        if event.event_type == EventType.METRIC_RECORDED:
+            return self._adapters.get("influxdb")
+        
+        # Default → MongoDB
+        return self._adapters.get("mongodb")
+    
+    def summary(self) -> dict:
+        return {
+            "adapters": list(self._adapters.keys()),
+            "events_logged": len(self._event_log),
+        }

src/monkey_brain/persistence/mongodb_adapter.py

@@ -0,0 +1,91 @@
+"""MongoDB Adapter — canonical source of truth.
+
+Responsibilities:
+- Agents, Users, Organizations
+- Workflows, Pipelines, Capabilities
+- Process Definitions, Documents
+- Knowledge Objects, Runtime Metadata
+
+MongoDB stores entities.
+MongoDB never stores execution history.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from src.monkey_brain.persistence.adapters import IStoreAdapter
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+
+
+class MongoDBAdapter(IStoreAdapter):
+    """MongoDB persistence adapter."""
+    
+    def __init__(self, url: str = "mongodb://localhost:27017", database: str = "agentos"):
+        self._url = url
+        self._database = database
+        self._client = None
+        self._db = None
+        self._connected = False
+    
+    @property
+    def name(self) -> str:
+        return "mongodb"
+    
+    async def connect(self) -> None:
+        try:
+            from motor.motor_asyncio import AsyncIOMotorClient
+            self._client = AsyncIOMotorClient(self._url)
+            self._db = self._client[self._database]
+            self._connected = True
+        except ImportError:
+            self._connected = False
+    
+    async def disconnect(self) -> None:
+        if self._client:
+            self._client.close()
+        self._connected = False
+    
+    async def health(self) -> dict[str, Any]:
+        return {
+            "status": "healthy" if self._connected else "unhealthy",
+            "database": self._database,
+        }
+    
+    async def persist(self, event: PersistenceEvent) -> dict[str, Any]:
+        if not self._connected:
+            return {"status": "disconnected"}
+        
+        collection = self._db[event.entity_type]
+        
+        if event.event_type == EventType.ENTITY_CREATED:
+            await collection.insert_one({"_id": event.entity_id, **event.data})
+            return {"status": "created", "entity_id": event.entity_id}
+        
+        elif event.event_type == EventType.ENTITY_UPDATED:
+            await collection.update_one(
+                {"_id": event.entity_id},
+                {"$set": event.data},
+                upsert=True,
+            )
+            return {"status": "updated", "entity_id": event.entity_id}
+        
+        elif event.event_type == EventType.ENTITY_DELETED:
+            await collection.delete_one({"_id": event.entity_id})
+            return {"status": "deleted", "entity_id": event.entity_id}
+        
+        return {"status": "ignored"}
+    
+    async def query(self, entity_type: str, entity_id: str | None = None) -> Any:
+        if not self._connected:
+            return None
+        
+        collection = self._db[entity_type]
+        
+        if entity_id:
+            return await collection.find_one({"_id": entity_id})
+        
+        cursor = collection.find().limit(100)
+        return await cursor.to_list(length=100)
+    
+    def is_connected(self) -> bool:
+        return self._connected

src/monkey_brain/persistence/redis_adapter.py

@@ -0,0 +1,93 @@
+"""Redis Adapter — runtime working memory.
+
+Responsibilities:
+- Active Sessions
+- Conversation State
+- Active Workflow State
+- Scheduler Queues
+- Locks, Runtime Cache
+- Temporary Variables
+
+Redis represents the runtime's working memory.
+Redis should survive only as long as execution requires.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from src.monkey_brain.persistence.adapters import IStoreAdapter
+from src.monkey_brain.persistence.events import PersistenceEvent, EventType
+
+
+class RedisAdapter(IStoreAdapter):
+    """Redis persistence adapter."""
+    
+    def __init__(self, url: str = "redis://localhost:6379"):
+        self._url = url
+        self._client = None
+        self._connected = False
+    
+    @property
+    def name(self) -> str:
+        return "redis"
+    
+    async def connect(self) -> None:
+        try:
+            import redis.asyncio as aioredis
+            self._client = aioredis.from_url(self._url, decode_responses=True)
+            self._connected = True
+        except ImportError:
+            self._connected = False
+    
+    async def disconnect(self) -> None:
+        if self._client:
+            await self._client.close()
+        self._connected = False
+    
+    async def health(self) -> dict[str, Any]:
+        return {
+            "status": "healthy" if self._connected else "unhealthy",
+        }
+    
+    async def persist(self, event: PersistenceEvent) -> dict[str, Any]:
+        if not self._connected:
+            return {"status": "disconnected"}
+        
+        key = f"{event.entity_type}:{event.entity_id}"
+        
+        if event.event_type in (EventType.ENTITY_CREATED, EventType.ENTITY_UPDATED):
+            await self._client.set(key, str(event.data))
+            return {"status": "stored", "key": key}
+        
+        elif event.event_type == EventType.ENTITY_DELETED:
+            await self._client.delete(key)
+            return {"status": "deleted", "key": key}
+        
+        return {"status": "ignored"}
+    
+    async def query(self, entity_type: str, entity_id: str | None = None) -> Any:
+        if not self._connected:
+            return None
+        
+        if entity_id:
+            key = f"{entity_type}:{entity_id}"
+            return await self._client.get(key)
+        
+        pattern = f"{entity_type}:*"
+        keys = await self._client.keys(pattern)
+        return keys
+    
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        if self._connected:
+            if ttl:
+                await self._client.setex(key, ttl, str(value))
+            else:
+                await self._client.set(key, str(value))
+    
+    async def get(self, key: str) -> Any:
+        if self._connected:
+            return await self._client.get(key)
+        return None
+    
+    def is_connected(self) -> bool:
+        return self._connected