velune-cli 0.9.0__py3-none-any.whl

velune/kernel/health.py

@@ -0,0 +1,54 @@
+"""Subsystem health monitoring and status collection."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+
+from velune.kernel.lifecycle import ComponentStatus, LifecycleCoordinator
+from velune.kernel.schemas import HealthReport
+
+logger = logging.getLogger("velune.kernel.health")
+
+
+class SubsystemHealthMonitor:
+    """Monitors system-wide component health, API response, and storage status."""
+
+    def __init__(self, coordinator: LifecycleCoordinator) -> None:
+        self._coordinator = coordinator
+        self._custom_checks: dict[str, Callable[[], dict]] = {}
+
+    def register_health_hook(self, name: str, hook: Callable[[], dict]) -> None:
+        """Register a custom diagnostic function for a subsystem."""
+        self._custom_checks[name] = hook
+
+    def check_subsystem(self, name: str) -> HealthReport:
+        """Evaluate and report a single subsystem's status and latency."""
+        status = self._coordinator.get_status(name)
+
+        start_time = time.perf_counter()
+        details = {}
+
+        if name in self._custom_checks:
+            try:
+                details = self._custom_checks[name]()
+            except Exception as e:
+                logger.error("Health hook failed for subsystem '%s': %s", name, e)
+                details = {"error": str(e)}
+                status = ComponentStatus.DEGRADED
+
+        latency_ms = (time.perf_counter() - start_time) * 1000.0
+
+        return HealthReport(
+            status=status,
+            latency_ms=latency_ms,
+            details=details,
+        )
+
+    def check_all(self) -> dict[str, HealthReport]:
+        """Aggregate health reports for all managed subsystems."""
+        reports = {}
+        for name in self._coordinator._components.keys():
+            reports[name] = self.check_subsystem(name)
+        return reports

velune/kernel/lifecycle.py

@@ -0,0 +1,143 @@
+"""Subsystem lifecycle manager and transition tracker."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from velune.kernel.schemas import ComponentStatus
+
+if TYPE_CHECKING:
+    from velune.kernel.config import VeluneConfig
+
+logger = logging.getLogger("velune.kernel.lifecycle")
+
+
+@runtime_checkable
+class Subsystem(Protocol):
+    """Lifecycle protocol for subsystems that need explicit startup or shutdown."""
+
+    async def initialize(self) -> None:
+        """Startup procedures for the component."""
+        ...
+
+    async def shutdown(self) -> None:
+        """Teardown procedures for the component."""
+        ...
+
+
+class LifecycleCoordinator:
+    """Orchestrates structured startup, health transitions, and graceful shutdown of subsystems."""
+
+    def __init__(self) -> None:
+        self._components: dict[str, Subsystem] = {}
+        self._states: dict[str, ComponentStatus] = {}
+        self._started = False
+        self.container: Any = None
+        self._config: VeluneConfig | None = None
+
+    def set_config(self, config: VeluneConfig) -> None:
+        """Attach a VeluneConfig so startup() can validate it before initialising subsystems."""
+        self._config = config
+
+    def register(self, name: str, component: Subsystem) -> None:
+        """Register a component for active lifecycle tracking."""
+        self._components[name] = component
+        self._states[name] = ComponentStatus.UNINITIALIZED
+        logger.debug("Component '%s' registered for lifecycle tracking.", name)
+
+    def get_status(self, name: str) -> ComponentStatus:
+        """Retrieve the current state of a registered component."""
+        return self._states.get(name, ComponentStatus.UNINITIALIZED)
+
+    def set_status(self, name: str, status: ComponentStatus) -> None:
+        """Explicitly set a component status."""
+        if name in self._states:
+            self._states[name] = status
+            logger.debug("Component '%s' transitioned to state: %s", name, status.value)
+
+    async def startup(self) -> None:
+        """Initialize all registered subsystems sequentially.
+
+        If a :class:`~velune.kernel.config.VeluneConfig` was attached via
+        :meth:`set_config`, it is validated first.  Any ``CRITICAL`` validation
+        errors abort startup immediately with a descriptive exception.
+        """
+        if self._started:
+            return
+
+        if self._config is not None:
+            from velune.kernel.config import ConfigValidationError  # noqa: F401
+
+            errors = self._config.validate()
+            critical = [e for e in errors if e.severity == "CRITICAL"]
+            if critical:
+                for err in critical:
+                    logger.critical(
+                        "Config validation failed — %s = %r: %s",
+                        err.field,
+                        err.value,
+                        err.reason,
+                    )
+                summary = "; ".join(f"{e.field}: {e.reason}" for e in critical)
+                raise RuntimeError(
+                    f"VeluneConfig has {len(critical)} critical error(s). "
+                    f"Startup aborted. Details: {summary}"
+                )
+            for warn in errors:
+                if warn.severity != "CRITICAL":
+                    logger.warning(
+                        "Config warning — %s = %r: %s",
+                        warn.field,
+                        warn.value,
+                        warn.reason,
+                    )
+
+        self._started = True
+        logger.info("Initializing Velune systems...")
+        for name, comp in self._components.items():
+            if self._states[name] != ComponentStatus.UNINITIALIZED:
+                continue
+
+            self._states[name] = ComponentStatus.INITIALIZING
+            try:
+                if hasattr(comp, "initialize") and callable(comp.initialize):
+                    await comp.initialize()
+                self._states[name] = ComponentStatus.HEALTHY
+                logger.info("Subsystem '%s' initialized successfully.", name)
+            except Exception as e:
+                self._states[name] = ComponentStatus.FAILED
+                logger.critical("Subsystem '%s' failed to initialize: %s", name, e)
+                raise e
+
+    async def shutdown(self) -> None:
+        """Shut down all registered subsystems gracefully in reverse order."""
+        if self.container and self.container.has("runtime.task_registry"):
+            try:
+                task_registry = self.container.get("runtime.task_registry")
+                await task_registry.cancel_all(timeout=10.0)
+            except Exception as e:
+                logger.error("Failed to cancel background tasks during shutdown: %s", e)
+
+        logger.info("Shutting down Velune systems...")
+        for name in reversed(list(self._components.keys())):
+            comp = self._components[name]
+            self._states[name] = ComponentStatus.SHUTTING_DOWN
+            try:
+                if hasattr(comp, "shutdown") and callable(comp.shutdown):
+                    await comp.shutdown()
+                elif hasattr(comp, "stop") and callable(comp.stop):
+                    if asyncio.iscoroutinefunction(comp.stop):
+                        await comp.stop()
+                    else:
+                        comp.stop()
+                self._states[name] = ComponentStatus.SHUTDOWN
+                logger.info("Subsystem '%s' shut down successfully.", name)
+            except Exception as e:
+                self._states[name] = ComponentStatus.FAILED
+                logger.error("Error shutting down subsystem '%s': %s", name, e)
+
+        self._components.clear()
+        self._states.clear()
+        self._started = False

velune/kernel/module.py

@@ -0,0 +1,17 @@
+from velune.kernel.bootstrap import RuntimeEnvironment, SubsystemModule
+
+
+def _create_cognitive_bus(env: RuntimeEnvironment):
+    from velune.events import CognitiveBus
+
+    return CognitiveBus()
+
+
+KERNEL_MODULES = [
+    SubsystemModule(
+        name="cognitive_bus",
+        factory=_create_cognitive_bus,
+        container_key="runtime.bus",
+        lifecycle_key="bus",
+    )
+]

velune/kernel/modules.py

@@ -0,0 +1,23 @@
+from velune.cognition.module import COGNITION_MODULES
+from velune.execution.module import EXECUTION_MODULES
+from velune.kernel.module import KERNEL_MODULES
+from velune.memory.module import MEMORY_MODULES
+from velune.models.module import MODEL_MODULES
+from velune.orchestration.module import ORCHESTRATION_MODULES
+from velune.providers.module import PROVIDER_MODULES
+from velune.repository.module import REPOSITORY_MODULES
+from velune.retrieval.module import RETRIEVAL_MODULES
+from velune.tools.module import TOOL_MODULES
+
+ALL_MODULES = (
+    KERNEL_MODULES
+    + PROVIDER_MODULES
+    + MODEL_MODULES
+    + REPOSITORY_MODULES
+    + MEMORY_MODULES
+    + RETRIEVAL_MODULES
+    + EXECUTION_MODULES
+    + TOOL_MODULES
+    + COGNITION_MODULES
+    + ORCHESTRATION_MODULES
+)

velune/kernel/registry.py

@@ -0,0 +1,96 @@
+"""Kernel component registry — string-keyed ServiceContainer with lazy factories."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+logger = logging.getLogger("velune.kernel.registry")
+
+T = TypeVar("T")
+
+
+class ServiceContainer:
+    """Component registry container supporting string-based lazy factories."""
+
+    def __init__(self) -> None:
+        self._services: dict[str, Any] = {}
+        self._factories: dict[str, Callable[[], Any]] = {}
+        self._singletons: dict[str, Any] = {}
+
+    def register(self, name: str, factory: Callable[[], T], singleton: bool = True) -> None:
+        """Register a service factory by key."""
+        if singleton:
+            self._factories[name] = factory
+        else:
+            self._services[name] = factory
+        logger.debug("Registered factory for service: '%s' (singleton=%s)", name, singleton)
+
+    def register_instance(self, name: str, instance: Any) -> None:
+        """Register a concrete service instance directly."""
+        self._singletons[name] = instance
+        logger.debug("Registered direct instance for service: '%s'", name)
+
+    def hot_swap(self, name: str, replacement: Any) -> None:
+        """Dynamically replace an active service instance or registry factory."""
+        logger.info("Hot-swapping service: '%s'", name)
+        self._singletons.pop(name, None)
+        self._factories.pop(name, None)
+        self._services.pop(name, None)  # Clear cached singleton too
+        self._singletons[name] = replacement
+
+    def get(self, name: str) -> Any:
+        """Retrieve a service instance by key. Resolves lazy factories if needed."""
+        if name in self._singletons:
+            return self._singletons[name]
+
+        if name in self._factories:
+            if name not in self._services:
+                factory = self._factories[name]
+                self._services[name] = factory()
+            return self._services[name]
+
+        if name in self._services:
+            callable_srv = self._services[name]
+            if callable(callable_srv):
+                return callable_srv()
+            return callable_srv
+
+        raise KeyError(f"Kernel Service not registered: {name}")
+
+    def has(self, name: str) -> bool:
+        """Check if a service is registered in any tier."""
+        return name in self._singletons or name in self._factories or name in self._services
+
+    def clear(self) -> None:
+        """Purge all registrations."""
+        self._services.clear()
+        self._factories.clear()
+        self._singletons.clear()
+        logger.debug("Kernel component registry cleared.")
+
+
+# Global system container
+_container = ServiceContainer()
+
+
+def inject(service_name: str):
+    """Decorator to inject a registered kernel component into function arguments."""
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            if service_name not in kwargs:
+                kwargs[service_name] = _container.get(service_name)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def get_container() -> ServiceContainer:
+    """Access the global system service container."""
+    return _container

velune/kernel/schemas.py

@@ -0,0 +1,28 @@
+"""Strictly-typed schemas for the Cognitive Kernel."""
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ComponentStatus(StrEnum):
+    """Execution status of registered kernel components."""
+
+    UNINITIALIZED = "uninitialized"
+    INITIALIZING = "initializing"
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    FAILED = "failed"
+    SHUTTING_DOWN = "shutting_down"
+    SHUTDOWN = "shutdown"
+
+
+class HealthReport(BaseModel):
+    """A report for individual subsystem health."""
+
+    status: ComponentStatus
+    latency_ms: float = 0.0
+    details: dict[str, Any] = Field(default_factory=dict)
+    last_check: datetime = Field(default_factory=lambda: datetime.now(tz=UTC))

velune/main.py

@@ -0,0 +1,9 @@
+"""Public CLI entry point for Velune."""
+
+from velune.cli.app import app
+
+__all__ = ["app"]
+
+
+if __name__ == "__main__":
+    app()

velune/mcp/__init__.py

@@ -0,0 +1,9 @@
+"""Model Context Protocol (MCP) support for Velune."""
+
+from __future__ import annotations
+
+from velune.mcp.client import VeluneMCPClient
+from velune.mcp.config import load_mcp_servers
+from velune.mcp.server import VeluneMCPServer
+
+__all__ = ["VeluneMCPServer", "VeluneMCPClient", "load_mcp_servers"]

velune/mcp/client.py

@@ -0,0 +1,115 @@
+"""MCP client consuming external MCP servers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import Tool
+
+from velune.tools.base.tool import BaseTool
+
+
+class MCPToolWrapper(BaseTool):
+    """Wraps an external MCP tool as a Velune BaseTool."""
+
+    def __init__(self, client: VeluneMCPClient, name: str, description: str, input_schema: dict):
+        self.client = client
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+
+    def get_name(self) -> str:
+        # Namespace tool with the server name prefix to avoid collisions
+        return f"{self.client.server_name}_{self.name}"
+
+    def get_description(self) -> str:
+        return self.description
+
+    def get_schema(self) -> dict[str, Any]:
+        return self.input_schema
+
+    async def execute(self, **kwargs) -> Any:
+        if not self.client.session:
+            raise RuntimeError(f"Client for tool {self.get_name()} is not connected.")
+        result = await self.client.session.call_tool(self.name, arguments=kwargs)
+
+        # CallToolResult structure holds content. Let's parse text contents.
+        text_contents = []
+        if hasattr(result, "content") and result.content:
+            for content in result.content:
+                if hasattr(content, "text"):
+                    text_contents.append(content.text)
+                elif isinstance(content, dict) and "text" in content:
+                    text_contents.append(content["text"])
+                else:
+                    text_contents.append(str(content))
+        return "\n".join(text_contents) if text_contents else str(result)
+
+
+class VeluneMCPClient:
+    """Connects to external MCP servers and exposes them as Velune tools."""
+
+    def __init__(self, server_url: str, server_name: str):
+        self.server_url = server_url
+        self.server_name = server_name
+        self._sse_ctx = None
+        self._session_ctx = None
+        self.session = None
+        self.raw_tools: list[Tool] = []
+
+    async def connect(self) -> list[dict]:
+        """Connect and return available tools."""
+        from mcp import ClientSession
+        from mcp.client.sse import sse_client
+
+        self._sse_ctx = sse_client(self.server_url)
+        self._read, self._write = await self._sse_ctx.__aenter__()
+
+        self._session_ctx = ClientSession(self._read, self._write)
+        self.session = await self._session_ctx.__aenter__()
+        await self.session.initialize()
+
+        tools_result = await self.session.list_tools()
+        self.raw_tools = tools_result.tools
+
+        # Convert tools to list of dict
+        result = []
+        for tool in self.raw_tools:
+            result.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description or "",
+                    "inputSchema": tool.inputSchema,
+                }
+            )
+        return result
+
+    def to_velune_tools(self) -> list[BaseTool]:
+        """Convert MCP tools to Velune BaseTool wrappers."""
+        velune_tools = []
+        for tool in self.raw_tools:
+            velune_tools.append(
+                MCPToolWrapper(
+                    client=self,
+                    name=tool.name,
+                    description=tool.description or "",
+                    input_schema=tool.inputSchema,
+                )
+            )
+        return velune_tools
+
+    async def disconnect(self) -> None:
+        """Disconnect and clean up resources."""
+        if self._session_ctx:
+            try:
+                await self._session_ctx.__aexit__(None, None, None)
+            except Exception:
+                pass
+            self._session_ctx = None
+            self.session = None
+        if self._sse_ctx:
+            try:
+                await self._sse_ctx.__aexit__(None, None, None)
+            except Exception:
+                pass
+            self._sse_ctx = None

velune/mcp/config.py

@@ -0,0 +1,19 @@
+"""Configuration utility for loading external MCP servers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from velune.kernel.config import ConfigLoader
+
+
+def load_mcp_servers(config_path: Path | None = None) -> dict[str, str]:
+    """Load external MCP server configurations from velune.toml."""
+    try:
+        loader = ConfigLoader(config_path)
+        config = loader.load()
+        if hasattr(config, "mcp") and config.mcp:
+            return config.mcp.servers
+    except Exception:
+        pass
+    return {}