monkeybrain-runtime 1.0.0__py3-none-any.whl

src/cerebellum/key_manager.py

@@ -0,0 +1,129 @@
+"""Key Manager — user-managed API keys and configuration.
+
+Users manage their own keys through the API.
+Keys are stored securely in the local database.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class ApiKey:
+    """An API key record."""
+    
+    key_id: str = field(default_factory=lambda: f"key-{uuid4().hex[:8]}")
+    service: str = ""
+    key_name: str = ""
+    key_hash: str = ""
+    api_url: str = ""
+    config: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    last_used: str = ""
+    is_active: bool = True
+
+
+class KeyManager:
+    """User-managed API key storage.
+    
+    Keys are stored in the local database.
+    Users manage their own keys through the API.
+    """
+    
+    def __init__(self, db_path: str = ".monkeybrain/keys.json"):
+        self._db_path = db_path
+        self._keys: dict[str, ApiKey] = {}
+        self._load()
+    
+    def _load(self) -> None:
+        """Load keys from disk."""
+        if os.path.exists(self._db_path):
+            try:
+                with open(self._db_path, 'r') as f:
+                    data = json.load(f)
+                for key_data in data.get('keys', []):
+                    key = ApiKey(**key_data)
+                    self._keys[key.key_id] = key
+            except Exception:
+                pass
+    
+    def _save(self) -> None:
+        """Save keys to disk."""
+        os.makedirs(os.path.dirname(self._db_path), exist_ok=True)
+        with open(self._db_path, 'w') as f:
+            json.dump({
+                'keys': [
+                    {
+                        'key_id': k.key_id,
+                        'service': k.service,
+                        'key_name': k.key_name,
+                        'key_hash': k.key_hash,
+                        'api_url': k.api_url,
+                        'config': k.config,
+                        'created_at': k.created_at,
+                        'is_active': k.is_active,
+                    }
+                    for k in self._keys.values()
+                ]
+            }, f, indent=2)
+    
+    def add_key(self, service: str, key_name: str, api_key: str, api_url: str = "", config: dict[str, Any] | None = None) -> ApiKey:
+        """Add a new API key."""
+        key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]
+        
+        api_key_record = ApiKey(
+            service=service,
+            key_name=key_name,
+            key_hash=key_hash,
+            api_url=api_url,
+            config=config or {},
+        )
+        
+        self._keys[api_key_record.key_id] = api_key_record
+        self._save()
+        return api_key_record
+    
+    def get_key(self, key_id: str) -> ApiKey | None:
+        return self._keys.get(key_id)
+    
+    def get_keys_by_service(self, service: str) -> list[ApiKey]:
+        return [k for k in self._keys.values() if k.service == service and k.is_active]
+    
+    def get_all_keys(self) -> list[ApiKey]:
+        return list(self._keys.values())
+    
+    def remove_key(self, key_id: str) -> bool:
+        if key_id in self._keys:
+            del self._keys[key_id]
+            self._save()
+            return True
+        return False
+    
+    def get_config_for_service(self, service: str) -> dict[str, Any]:
+        """Get merged config for a service."""
+        keys = self.get_keys_by_service(service)
+        if not keys:
+            return {}
+        
+        config = {}
+        for key in keys:
+            config.update(key.config)
+            if key.api_url:
+                config['api_url'] = key.api_url
+        return config
+    
+    def summary(self) -> dict:
+        by_service = {}
+        for k in self._keys.values():
+            by_service[k.service] = by_service.get(k.service, 0) + 1
+        return {
+            "total_keys": len(self._keys),
+            "by_service": by_service,
+        }

src/cerebellum/keystore.py

@@ -0,0 +1,179 @@
+"""Secure Keystore — user-scrypted API key management.
+
+Each user has their own isolated key store.
+Capabilities read keys from the keystore by user.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+def _generate_key() -> bytes:
+    from cryptography.fernet import Fernet
+    return Fernet.generate_key()
+
+
+def _encrypt(data: str, key: bytes) -> str:
+    from cryptography.fernet import Fernet
+    return Fernet(key).encrypt(data.encode()).decode()
+
+
+def _decrypt(encrypted: str, key: bytes) -> str:
+    from cryptography.fernet import Fernet
+    return Fernet(key).decrypt(encrypted.encode()).decode()
+
+
+@dataclass
+class SecureKey:
+    """An encrypted API key record."""
+    
+    key_id: str = field(default_factory=lambda: f"key-{uuid4().hex[:12]}")
+    user_id: str = ""
+    service: str = ""
+    key_name: str = ""
+    encrypted_key: str = ""
+    api_url: str = ""
+    config: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    is_active: bool = True
+    
+    def to_public(self) -> dict:
+        return {
+            "key_id": self.key_id,
+            "user_id": self.user_id,
+            "service": self.service,
+            "key_name": self.key_name,
+            "api_url": self.api_url,
+            "created_at": self.created_at,
+            "is_active": self.is_active,
+        }
+
+
+class SecureKeystore:
+    """User-scoped encrypted API key storage."""
+    
+    def __init__(self, master_key: str | None = None, db_path: str = ".monkeybrain/keystore"):
+        self._db_path = db_path
+        self._master_key = (master_key or os.getenv("AGENTOS_MASTER_KEY", "")).encode()
+        if not self._master_key:
+            self._master_key = _generate_key()
+        self._keys: dict[str, SecureKey] = {}
+        self._load()
+    
+    def _derive_key(self) -> bytes:
+        return hashlib.sha256(self._master_key).digest()[:32]
+    
+    def _encrypt_value(self, value: str) -> str:
+        key = base64.urlsafe_b64encode(self._derive_key())
+        return _encrypt(value, key)
+    
+    def _decrypt_value(self, encrypted: str) -> str:
+        key = base64.urlsafe_b64encode(self._derive_key())
+        return _decrypt(encrypted, key)
+    
+    def _load(self) -> None:
+        if os.path.exists(self._db_path):
+            try:
+                with open(self._db_path, 'r') as f:
+                    data = json.load(f)
+                for key_data in data.get('keys', []):
+                    key = SecureKey(**key_data)
+                    self._keys[key.key_id] = key
+            except Exception:
+                pass
+    
+    def _save(self) -> None:
+        os.makedirs(os.path.dirname(self._db_path) if os.path.dirname(self._db_path) else '.', exist_ok=True)
+        with open(self._db_path, 'w') as f:
+            json.dump({
+                'keys': [
+                    {
+                        'key_id': k.key_id,
+                        'user_id': k.user_id,
+                        'service': k.service,
+                        'key_name': k.key_name,
+                        'encrypted_key': k.encrypted_key,
+                        'api_url': k.api_url,
+                        'config': k.config,
+                        'created_at': k.created_at,
+                        'is_active': k.is_active,
+                    }
+                    for k in self._keys.values()
+                ]
+            }, f, indent=2)
+        os.chmod(self._db_path, 0o600)
+    
+    def add_key(self, user_id: str, service: str, key_name: str, api_key: str, api_url: str = "", config: dict[str, Any] | None = None) -> dict:
+        """Add an encrypted API key for a specific user."""
+        encrypted = self._encrypt_value(api_key)
+        key = SecureKey(
+            user_id=user_id,
+            service=service,
+            key_name=key_name,
+            encrypted_key=encrypted,
+            api_url=api_url,
+            config=config or {},
+        )
+        self._keys[key.key_id] = key
+        self._save()
+        return key.to_public()
+    
+    def get_key(self, key_id: str, user_id: str) -> str | None:
+        """Get decrypted API key (user-scoped)."""
+        key = self._keys.get(key_id)
+        if key and key.user_id == user_id and key.encrypted_key:
+            return self._decrypt_value(key.encrypted_key)
+        return None
+    
+    def get_config(self, service: str, user_id: str) -> dict[str, Any]:
+        """Get merged config for a service (user-scoped)."""
+        keys = [k for k in self._keys.values() if k.service == service and k.user_id == user_id and k.is_active]
+        if not keys:
+            return {}
+        
+        config = {}
+        for key in keys:
+            config.update(key.config)
+            if key.api_url:
+                config['api_url'] = key.api_url
+            api_key = self.get_key(key.key_id, user_id)
+            if api_key:
+                config['api_key'] = api_key
+        return config
+    
+    def list_keys(self, user_id: str, service: str | None = None) -> list[dict]:
+        """List keys for a user (without key material)."""
+        keys = [k for k in self._keys.values() if k.user_id == user_id]
+        if service:
+            keys = [k for k in keys if k.service == service]
+        return [k.to_public() for k in keys]
+    
+    def remove_key(self, key_id: str, user_id: str) -> bool:
+        """Remove a key (user-scoped)."""
+        key = self._keys.get(key_id)
+        if key and key.user_id == user_id:
+            del self._keys[key_id]
+            self._save()
+            return True
+        return False
+    
+    def summary(self, user_id: str | None = None) -> dict:
+        keys = self._keys.values()
+        if user_id:
+            keys = [k for k in keys if k.user_id == user_id]
+        by_service = {}
+        for k in keys:
+            by_service[k.service] = by_service.get(k.service, 0) + 1
+        return {
+            "total_keys": len(keys),
+            "by_service": by_service,
+            "encrypted": True,
+        }

src/cerebellum/lifecycle.py

@@ -0,0 +1,54 @@
+"""Capability Lifecycle — uniform lifecycle for all capabilities.
+
+Every capability must implement:
+Initialize → Configure → Validate → Register → Discover → Execute → Observe → Shutdown
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any
+
+
+class CapabilityState(str, Enum):
+    """Capability lifecycle states."""
+    CREATED = "created"
+    INITIALIZED = "initialized"
+    CONFIGURED = "configured"
+    VALIDATED = "validated"
+    REGISTERED = "registered"
+    READY = "ready"
+    EXECUTING = "executing"
+    OBSERVING = "observing"
+    SHUTDOWN = "shutdown"
+    ERROR = "error"
+
+
+class ICapabilityLifecycle(ABC):
+    """Interface for capability lifecycle management."""
+    
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the capability."""
+        ...
+    
+    @abstractmethod
+    async def configure(self, config: dict[str, Any]) -> None:
+        """Configure the capability."""
+        ...
+    
+    @abstractmethod
+    async def validate(self) -> bool:
+        """Validate the capability configuration."""
+        ...
+    
+    @abstractmethod
+    async def health(self) -> dict[str, Any]:
+        """Check capability health."""
+        ...
+    
+    @abstractmethod
+    async def shutdown(self) -> None:
+        """Shutdown the capability."""
+        ...

src/cerebellum/metadata.py

@@ -0,0 +1,61 @@
+"""Capability Metadata — describes a capability's properties.
+
+Every capability must expose metadata.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CapabilityMetadata:
+    """Metadata for a capability."""
+    
+    name: str = ""
+    version: str = "1.0.0"
+    description: str = ""
+    author: str = ""
+    category: str = ""  # api | database | ai | workflow | storage | communication
+    tags: list[str] = field(default_factory=list)
+    
+    # Capabilities
+    supported_inputs: list[str] = field(default_factory=list)
+    supported_outputs: list[str] = field(default_factory=list)
+    supported_protocols: list[str] = field(default_factory=list)
+    
+    # Dependencies
+    required_permissions: list[str] = field(default_factory=list)
+    required_secrets: list[str] = field(default_factory=list)
+    required_config: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+    
+    # Health
+    health_check_endpoint: str = ""
+    
+    # Versioning
+    semantic_version: str = "1.0.0"
+    compatibility_version: str = "1.0"
+    deprecation_date: str | None = None
+    
+    # Documentation
+    documentation_url: str = ""
+    examples: list[dict[str, Any]] = field(default_factory=list)
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "author": self.author,
+            "category": self.category,
+            "tags": self.tags,
+            "supported_inputs": self.supported_inputs,
+            "supported_outputs": self.supported_outputs,
+            "supported_protocols": self.supported_protocols,
+            "required_permissions": self.required_permissions,
+            "required_secrets": self.required_secrets,
+            "required_config": self.required_config,
+            "dependencies": self.dependencies,
+        }

src/cerebellum/operator/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from src.monkey_brain.kernel.dag import DAGNode
+
+
+class PlaceholderCapability:
+    """Semantic capability placeholder.
+
+    Subclasses represent operator semantics only. Backend adapters
+    (CMMS, MES, ERP, GraphRAG, Neo4j, Mongo, etc.) are wired in later.
+    """
+
+    async def execute(
+        self,
+        context: Any,
+        node: DAGNode,
+    ) -> dict[str, Any]:
+        return {
+            "node_id": node.node_id,
+            "operator_type": node.operator_type,
+            "status": "executed",
+            "metadata": dict(node.metadata),
+        }

src/cerebellum/peripheral.py

@@ -0,0 +1,92 @@
+"""Peripheral — hardware or service integration point.
+
+A Peripheral represents a connection to an external system:
+- Database (MongoDB, Neo4j, InfluxDB)
+- Message Queue (MQTT, Kafka, NATS)
+- API (REST, GraphQL, gRPC)
+- File System
+- Device (OPC-UA, Modbus)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+
+class PeripheralType(str, Enum):
+    DATABASE = "database"
+    MESSAGE_QUEUE = "message_queue"
+    API = "api"
+    FILE_SYSTEM = "file_system"
+    DEVICE = "device"
+    STREAM = "stream"
+    CACHE = "cache"
+
+
+@dataclass
+class PeripheralHealth:
+    """Health status of a peripheral."""
+    status: str = "healthy"  # healthy | degraded | unhealthy
+    latency_ms: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Peripheral:
+    """A connection to an external system.
+    
+    Responsibilities:
+    - Manage connection lifecycle
+    - Report health status
+    - Provide access to external resources
+    
+    The Peripheral never:
+    - Makes execution decisions
+    - Transforms data
+    - Manages capabilities
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        type: PeripheralType,
+        config: dict[str, Any] | None = None,
+    ):
+        self.name = name
+        self.type = type
+        self.config = config or {}
+        self._connected = False
+        self._id = f"periph-{uuid4().hex[:8]}"
+    
+    @property
+    def id(self) -> str:
+        return self._id
+    
+    async def connect(self) -> None:
+        """Establish connection to peripheral."""
+        self._connected = True
+    
+    async def disconnect(self) -> None:
+        """Close connection to peripheral."""
+        self._connected = False
+    
+    async def health(self) -> PeripheralHealth:
+        """Check peripheral health."""
+        return PeripheralHealth(
+            status="healthy" if self._connected else "unhealthy",
+            metadata={"name": self.name, "type": self.type.value},
+        )
+    
+    def is_connected(self) -> bool:
+        return self._connected
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self._id,
+            "name": self.name,
+            "type": self.type.value,
+            "connected": self._connected,
+            "config": {k: v for k, v in self.config.items() if k != "password"},
+        }

src/cerebellum/registry.py

@@ -0,0 +1,98 @@
+"""Registry — capability discovery and publishing.
+
+The Registry is optional. Only the protocol is mandatory.
+
+Supports:
+- Local: in-memory, single process
+- Enterprise: shared, multi-process
+- Public: community, discoverable
+- Offline: cached, no network
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from src.cerebellum.capability import CapabilityManifest
+
+
+@dataclass
+class RegistryQuery:
+    """Query for capability discovery."""
+    
+    name: str | None = None
+    tags: list[str] | None = None
+    peripheral_type: str | None = None
+    author: str | None = None
+    min_version: str | None = None
+    limit: int = 10
+
+
+class Registry:
+    """Capability registry protocol.
+    
+    Responsibilities:
+    - Publish capabilities
+    - Discover capabilities
+    - Resolve capabilities by ID
+    - Remove capabilities
+    
+    The Registry never:
+    - Executes capabilities
+    - Makes execution decisions
+    - Manages connections
+    """
+    
+    def __init__(self):
+        self._capabilities: dict[str, CapabilityManifest] = {}
+    
+    async def publish(self, manifest: CapabilityManifest) -> str:
+        """Publish a capability to the registry.
+        
+        Returns: capability_id
+        """
+        if not manifest.capability_id:
+            manifest.capability_id = f"cap-{uuid4().hex[:8]}"
+        if not manifest.published_at:
+            manifest.published_at = datetime.now(timezone.utc).isoformat()
+        
+        self._capabilities[manifest.capability_id] = manifest
+        return manifest.capability_id
+    
+    async def discover(self, query: RegistryQuery) -> list[CapabilityManifest]:
+        """Discover capabilities matching query."""
+        results = list(self._capabilities.values())
+        
+        if query.name:
+            results = [m for m in results if query.name.lower() in m.name.lower()]
+        
+        if query.tags:
+            results = [m for m in results if any(t in m.tags for t in query.tags)]
+        
+        if query.peripheral_type:
+            results = [m for m in results if m.peripheral_type == query.peripheral_type]
+        
+        if query.author:
+            results = [m for m in results if m.author == query.author]
+        
+        return results[:query.limit]
+    
+    async def resolve(self, capability_id: str) -> CapabilityManifest | None:
+        """Resolve a capability by ID."""
+        return self._capabilities.get(capability_id)
+    
+    async def remove(self, capability_id: str) -> bool:
+        """Remove a capability from registry."""
+        if capability_id in self._capabilities:
+            del self._capabilities[capability_id]
+            return True
+        return False
+    
+    def count(self) -> int:
+        return len(self._capabilities)
+    
+    def list_all(self) -> list[CapabilityManifest]:
+        return list(self._capabilities.values())