velune-cli 0.9.0__py3-none-any.whl

velune/kernel/__init__.py

@@ -0,0 +1,55 @@
+"""Cognitive Kernel (the OS layer for Velune)."""
+
+from velune.events import CognitiveBus, Event, EventBus, EventHandler, Subscription
+from velune.kernel.config import (
+    ConfigLoader,
+    ConfigService,
+    ConfigValidationError,
+    ContextConfig,
+    ExecutionConfig,
+    MemoryConfig,
+    ProjectConfig,
+    ProvidersConfig,
+    RetrievalConfig,
+    VeluneConfig,
+    WorkspaceConfig,
+    get_default_config,
+)
+from velune.kernel.health import SubsystemHealthMonitor
+from velune.kernel.lifecycle import LifecycleCoordinator, Subsystem
+from velune.kernel.registry import ServiceContainer, get_container, inject
+from velune.kernel.schemas import ComponentStatus, HealthReport
+
+__all__ = [
+    # Schemas
+    "ComponentStatus",
+    "Event",
+    "HealthReport",
+    # Bus
+    "CognitiveBus",
+    "Subscription",
+    "EventBus",
+    "EventHandler",
+    # Registry
+    "ServiceContainer",
+    "inject",
+    "get_container",
+    # Lifecycle
+    "LifecycleCoordinator",
+    "Subsystem",
+    # Config
+    "VeluneConfig",
+    "ConfigValidationError",
+    "ProjectConfig",
+    "WorkspaceConfig",
+    "ContextConfig",
+    "MemoryConfig",
+    "RetrievalConfig",
+    "ExecutionConfig",
+    "ProvidersConfig",
+    "ConfigLoader",
+    "ConfigService",
+    "get_default_config",
+    # Health
+    "SubsystemHealthMonitor",
+]

velune/kernel/bootstrap.py

@@ -0,0 +1,125 @@
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from velune.kernel.config import VeluneConfig
+from velune.kernel.lifecycle import LifecycleCoordinator
+from velune.kernel.registry import ServiceContainer
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SubsystemModule:
+    """Declares a subsystem's factory and dependencies."""
+
+    name: str
+    factory: Callable[["RuntimeEnvironment"], Any]
+    container_key: str
+    lifecycle_key: str | None = None  # None = not lifecycle-managed
+    dependencies: list[str] = field(default_factory=list)  # container keys this needs
+
+
+@dataclass
+class RuntimeEnvironment:
+    """Everything a subsystem factory needs to initialize itself."""
+
+    workspace: Path
+    config: VeluneConfig
+    container: ServiceContainer
+    lifecycle: LifecycleCoordinator
+    verbose: bool = False
+
+
+class RuntimeBootstrapper:
+    def __init__(self) -> None:
+        self._modules: list[SubsystemModule] = []
+
+    def register_module(self, module: SubsystemModule) -> None:
+        self._modules.append(module)
+
+    def bootstrap(self, env: RuntimeEnvironment) -> None:
+        """Initialize all modules in dependency order."""
+        from velune.core.startup_profiler import mark
+        from velune.core.task_registry import BackgroundTaskRegistry
+
+        registry = BackgroundTaskRegistry()
+        env.container.register_instance("runtime.task_registry", registry)
+
+        from velune.hardware.detector import HardwareDetector
+
+        hardware_profile = HardwareDetector().detect()
+        env.container.register_instance("runtime.hardware", hardware_profile)
+        mark("hardware detected")
+
+        # Modules with lifecycle_key set are lifecycle-critical (startup/shutdown
+        # managed by LifecycleCoordinator). A factory failure aborts bootstrap.
+        # Modules with lifecycle_key=None are optional; a factory failure is
+        # logged and that module is skipped, letting the rest of the system start.
+        resolved = self._topological_sort()
+        for module in resolved:
+            try:
+                instance = module.factory(env)
+                mark(f"module: {module.name}")
+            except Exception as exc:
+                if module.lifecycle_key:
+                    _logger.critical(
+                        "Critical module '%s' (%s) failed to initialize: %s",
+                        module.name,
+                        module.container_key,
+                        exc,
+                    )
+                    raise
+                _logger.warning(
+                    "Optional module '%s' (%s) failed to initialize, skipping: %s",
+                    module.name,
+                    module.container_key,
+                    exc,
+                )
+                continue
+            env.container.register_instance(module.container_key, instance)
+            if module.lifecycle_key:
+                env.lifecycle.register(module.lifecycle_key, instance)
+
+    def _topological_sort(self) -> list[SubsystemModule]:
+        # Kahn's algorithm on dependency graph
+        in_degree = {}
+        graph = {}
+        key_to_mod = {mod.container_key: mod for mod in self._modules}
+
+        for mod in self._modules:
+            in_degree[mod.container_key] = 0
+            graph[mod.container_key] = []
+
+        for mod in self._modules:
+            # only consider dependencies that are other modules
+            for dep in mod.dependencies:
+                if dep in key_to_mod:
+                    graph[dep].append(mod.container_key)
+                    in_degree[mod.container_key] += 1
+
+        # Find all modules with in_degree == 0
+        from collections import deque
+
+        queue = deque(
+            [mod.container_key for mod in self._modules if in_degree[mod.container_key] == 0]
+        )
+
+        resolved_keys = []
+        while queue:
+            node = queue.popleft()
+            resolved_keys.append(node)
+            for neighbor in graph[node]:
+                in_degree[neighbor] -= 1
+                if in_degree[neighbor] == 0:
+                    queue.append(neighbor)
+
+        if len(resolved_keys) != len(self._modules):
+            unresolved = set(key_to_mod.keys()) - set(resolved_keys)
+            raise ValueError(
+                f"Circular dependency or missing module dependency detected in bootstrap! Unresolved: {unresolved}"
+            )
+
+        return [key_to_mod[key] for key in resolved_keys]

velune/kernel/config.py

@@ -0,0 +1,426 @@
+"""Layered configuration engine with env overrides, schemas, and workspace discovery."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import toml
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+@dataclass
+class ConfigValidationError:
+    """A single configuration validation problem."""
+
+    field: str
+    value: str | None
+    reason: str
+    severity: str = "CRITICAL"  # "CRITICAL" or "WARNING"
+
+
+class ProjectConfig(BaseModel):
+    """Project-level metadata."""
+
+    name: str = "velune"
+    version: str = "0.1.0"
+
+
+class WorkspaceConfig(BaseModel):
+    """Workspace cognition settings."""
+
+    index_on_init: bool = True
+    watch_files: bool = True
+    git_aware: bool = True
+    root: Path | None = None
+
+
+class ContextConfig(BaseModel):
+    """Context window budgeting settings."""
+
+    max_tokens: int = 128000
+    compression_threshold: float = Field(default=0.8, ge=0.0, le=1.0)
+    priority_tiers: list[str] = Field(default_factory=lambda: ["critical", "high", "medium", "low"])
+
+
+class MemoryConfig(BaseModel):
+    """Memory retention and thresholds."""
+
+    working_memory_ttl: int = 3600  # seconds
+    episodic_retention_days: int = 30
+    semantic_threshold: float = Field(default=0.85, ge=0.0, le=1.0)
+    graph_enabled: bool = True
+    storage_dir: Path | None = None
+
+
+class RetrievalConfig(BaseModel):
+    """Hybrid retrieval fusion weightings."""
+
+    vector_weight: float = Field(default=0.5, ge=0.0, le=1.0)
+    lexical_weight: float = Field(default=0.3, ge=0.0, le=1.0)
+    graph_weight: float = Field(default=0.2, ge=0.0, le=1.0)
+    rerank_top_k: int = Field(default=10, ge=1)
+
+
+class ExecutionConfig(BaseModel):
+    """Safety and sandboxing options."""
+
+    sandbox_enabled: bool = True
+    auto_snapshot: bool = True
+    require_confirmation: bool = True
+    dry_run_default: bool = False
+    low_resource_mode: bool = False
+    allowed_executables: list[str] = Field(
+        default_factory=lambda: [
+            "python",
+            "python3",
+            "pytest",
+            "ruff",
+            "mypy",
+            "git",
+            "node",
+            "npm",
+            "cargo",
+            "go",
+            "make",
+            "cmake",
+            "gcc",
+            "clang",
+            "echo",
+            "cat",
+            "ls",
+            "find",
+            "grep",
+        ]
+    )
+
+
+class ProviderEntry(BaseModel):
+    """Target address and API key names for LLM providers."""
+
+    api_key_env: str | None = None
+    base_url: str | None = None
+
+
+class ProvidersConfig(BaseModel):
+    """Configuration for active and fallback models."""
+
+    default_provider: str = "openai"
+    fallback_providers: list[str] = Field(default_factory=lambda: ["anthropic", "ollama"])
+    cost_threshold_usd: float = Field(
+        default=0.01,
+        description="Prompt for confirmation before cloud calls estimated to cost more than this (USD). Set to 0 to always ask.",
+    )
+    openai: ProviderEntry | None = Field(
+        default_factory=lambda: ProviderEntry(
+            api_key_env="OPENAI_API_KEY", base_url="https://api.openai.com/v1"
+        )
+    )
+    anthropic: ProviderEntry | None = Field(
+        default_factory=lambda: ProviderEntry(
+            api_key_env="ANTHROPIC_API_KEY", base_url="https://api.anthropic.com"
+        )
+    )
+    ollama: ProviderEntry | None = Field(
+        default_factory=lambda: ProviderEntry(base_url="http://localhost:11434")
+    )
+    lmstudio: ProviderEntry | None = Field(
+        default_factory=lambda: ProviderEntry(base_url="http://localhost:1234/v1")
+    )
+    llamacpp: ProviderEntry | None = Field(default_factory=lambda: ProviderEntry(base_url=""))
+    huggingface: ProviderEntry | None = Field(
+        default_factory=lambda: ProviderEntry(
+            api_key_env="HF_TOKEN", base_url="https://api-inference.huggingface.co"
+        )
+    )
+
+
+class TelemetryConfig(BaseModel):
+    """Observability options."""
+
+    enabled: bool = True
+    export_otlp: bool = False
+    log_level: str = "INFO"
+
+
+class MCPConfig(BaseModel):
+    """MCP configuration settings."""
+
+    servers: dict[str, str] = Field(default_factory=dict)
+
+
+class CognitionConfig(BaseModel):
+    """Cognitive routing and agent council settings."""
+
+    max_council_tier: str = "full"  # instant, minimal, standard, full
+    default_tier_override: str = "auto"  # auto, instant, minimal, standard, full
+
+
+class VeluneConfig(BaseSettings):
+    """Root configuration tree.
+
+    Field values are resolved in this priority order (highest first):
+    1. Explicit constructor kwargs (e.g. from TOML file data)
+    2. Environment variables prefixed with ``VELUNE_`` (nested via ``__``)
+    3. A ``.env`` file in the working directory
+    4. Hard-coded field defaults
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="VELUNE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+        env_ignore_empty=True,
+    )
+
+    project: ProjectConfig = Field(default_factory=ProjectConfig)
+    workspace: WorkspaceConfig = Field(default_factory=WorkspaceConfig)
+    context: ContextConfig = Field(default_factory=ContextConfig)
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    retrieval: RetrievalConfig = Field(default_factory=RetrievalConfig)
+    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
+    providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
+    telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig)
+    mcp: MCPConfig = Field(default_factory=MCPConfig)
+    cognition: CognitionConfig = Field(default_factory=CognitionConfig)
+
+    # ---------------------------------------------------------------------------
+    # Startup validation
+    # ---------------------------------------------------------------------------
+
+    def validate(self) -> list[ConfigValidationError]:
+        """Validate the configuration and return any problems found.
+
+        Returns a list of :class:`ConfigValidationError`.  An empty list means
+        the configuration is healthy.  Callers should treat ``severity="CRITICAL"``
+        errors as startup-blocking failures.
+        """
+        errors: list[ConfigValidationError] = []
+
+        provider_name = self.providers.default_provider
+        provider_entry: ProviderEntry | None = getattr(self.providers, provider_name, None)
+
+        if not isinstance(provider_entry, ProviderEntry):
+            errors.append(
+                ConfigValidationError(
+                    field="providers.default_provider",
+                    value=provider_name,
+                    reason=(
+                        f"Provider '{provider_name}' is not defined in the [providers] section. "
+                        f"Add a [{provider_name}] entry or change default_provider."
+                    ),
+                    severity="CRITICAL",
+                )
+            )
+        else:
+            # Remote providers require an API key env var to be populated.
+            if provider_entry.api_key_env:
+                resolved = os.getenv(provider_entry.api_key_env)
+                if not resolved:
+                    errors.append(
+                        ConfigValidationError(
+                            field=f"providers.{provider_name}.api_key_env",
+                            value=provider_entry.api_key_env,
+                            reason=(
+                                f"Environment variable '{provider_entry.api_key_env}' is not set. "
+                                f"Provider '{provider_name}' requires an API key to function."
+                            ),
+                            severity="CRITICAL",
+                        )
+                    )
+
+        # Optional workspace root — validate if explicitly configured.
+        if self.workspace.root is not None:
+            wp = Path(self.workspace.root)
+            if not wp.exists():
+                errors.append(
+                    ConfigValidationError(
+                        field="workspace.root",
+                        value=str(wp),
+                        reason=f"Workspace path '{wp}' does not exist.",
+                        severity="CRITICAL",
+                    )
+                )
+            elif not os.access(wp, os.R_OK):
+                errors.append(
+                    ConfigValidationError(
+                        field="workspace.root",
+                        value=str(wp),
+                        reason=f"Workspace path '{wp}' exists but is not readable.",
+                        severity="CRITICAL",
+                    )
+                )
+
+        # Optional memory storage directory — validate writability if configured.
+        if self.memory.storage_dir is not None:
+            sd = Path(self.memory.storage_dir)
+            if not sd.exists():
+                errors.append(
+                    ConfigValidationError(
+                        field="memory.storage_dir",
+                        value=str(sd),
+                        reason=f"Storage directory '{sd}' does not exist.",
+                        severity="WARNING",
+                    )
+                )
+            elif not os.access(sd, os.W_OK):
+                errors.append(
+                    ConfigValidationError(
+                        field="memory.storage_dir",
+                        value=str(sd),
+                        reason=f"Storage directory '{sd}' exists but is not writable.",
+                        severity="CRITICAL",
+                    )
+                )
+
+        return errors
+
+    def save_to_project(self, workspace: Path) -> Path:
+        """Write only non-default values to .velune/config.toml.
+
+        Returns the path the file was written to.
+        """
+        project_config_dir = workspace / ".velune"
+        project_config_dir.mkdir(parents=True, exist_ok=True)
+        config_path = project_config_dir / "config.toml"
+
+        current_data = self.model_dump()
+        # Compare against hard-coded defaults, not an env-var-influenced instance.
+        default_data = _hardcoded_defaults()
+        non_default = _strip_defaults(current_data, default_data)
+
+        with open(config_path, "w", encoding="utf-8") as f:
+            toml.dump(non_default, f)
+
+        return config_path
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _hardcoded_defaults() -> dict:
+    """Return a pure-default VeluneConfig dict, unaffected by environment variables."""
+    instance = VeluneConfig.model_construct(
+        project=ProjectConfig(),
+        workspace=WorkspaceConfig(),
+        context=ContextConfig(),
+        memory=MemoryConfig(),
+        retrieval=RetrievalConfig(),
+        execution=ExecutionConfig(),
+        providers=ProvidersConfig(),
+        telemetry=TelemetryConfig(),
+        mcp=MCPConfig(),
+        cognition=CognitionConfig(),
+    )
+    return instance.model_dump()
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge *override* into *base*, returning a new dict."""
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _strip_defaults(current: dict, defaults: dict) -> dict:
+    """Return only entries in *current* that differ from *defaults*."""
+    result: dict = {}
+    for key, value in current.items():
+        if key not in defaults:
+            result[key] = value
+        elif isinstance(value, dict) and isinstance(defaults[key], dict):
+            stripped = _strip_defaults(value, defaults[key])
+            if stripped:
+                result[key] = stripped
+        elif value != defaults[key]:
+            result[key] = value
+    return result
+
+
+def get_default_config() -> VeluneConfig:
+    """Acquire standard default settings."""
+    return VeluneConfig()
+
+
+class ConfigLoader:
+    """Loads and overlays configuration from TOML and Environment variables."""
+
+    def __init__(self, config_path: Path | None = None) -> None:
+        self.config_path = config_path or self._find_config_path()
+
+    def _find_config_path(self) -> Path | None:
+        """Traverse upwards to locate velune.toml, or fall back to user home."""
+        try:
+            current_dir = Path.cwd()
+            while current_dir != current_dir.parent:
+                config_file = current_dir / "velune.toml"
+                if config_file.exists():
+                    return config_file
+                current_dir = current_dir.parent
+        except Exception:
+            pass
+
+        # Fallback to home directory config
+        home_config = Path.home() / ".velune" / "velune.toml"
+        if home_config.exists():
+            return home_config
+
+        return None
+
+    def load(self) -> VeluneConfig:
+        """Parse the TOML config file if it exists, otherwise return defaults.
+
+        Constructor kwargs take highest priority in BaseSettings, so TOML values
+        override env vars when an explicit config file is present.  When no config
+        file is found, ``VeluneConfig()`` is returned and env vars apply normally.
+        """
+        if not self.config_path or not self.config_path.exists():
+            return get_default_config()
+
+        try:
+            data = toml.load(self.config_path)
+            return VeluneConfig(**data)
+        except Exception:
+            return get_default_config()
+
+    def load_with_env_overrides(self) -> VeluneConfig:
+        """Load config from the TOML file (if present), with env var fallback.
+
+        Since ``VeluneConfig`` is now a ``BaseSettings``, environment variables
+        prefixed with ``VELUNE_`` are always consulted for any field not supplied
+        by the TOML file.
+        """
+        return self.load()
+
+
+@dataclass(slots=True)
+class ConfigService:
+    """Workspace-aware configuration service."""
+
+    workspace: Path
+    config_path: Path | None = None
+
+    def load(self) -> VeluneConfig:
+        """Load configuration using workspace priorities."""
+        resolved = self._resolve_config_path()
+        return ConfigLoader(resolved).load_with_env_overrides()
+
+    def _resolve_config_path(self) -> Path | None:
+        if self.config_path:
+            return self.config_path
+
+        workspace_config = self.workspace / "velune.toml"
+        if workspace_config.exists():
+            return workspace_config
+
+        return None

velune/kernel/entrypoint.py

@@ -0,0 +1,78 @@
+"""Single async runtime entry point for Velune.
+
+``asyncio.run`` is called **exactly once** in the entire codebase — inside
+``run_async()`` below.  Every module that needs to bridge from sync to async
+(CLI command callbacks, deprecated sync retrieval helpers, the daemon server)
+imports and calls ``run_async()`` instead of calling ``asyncio.run``
+directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+_T = TypeVar("_T")
+_logger = logging.getLogger(__name__)
+
+
+def _install_uvloop() -> None:
+    """Swap the default asyncio event-loop policy for uvloop if available."""
+    try:
+        import uvloop  # type: ignore[import-untyped]
+
+        asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+        _logger.debug("uvloop event-loop policy installed.")
+    except ImportError:
+        pass
+
+
+def run_async(coro: Coroutine[Any, Any, _T]) -> _T:
+    """Run *coro* to completion from a **synchronous** call site.
+
+    This is the **only** place in the entire Velune codebase that calls
+    ``asyncio.run``.  All other callers must import and use this function.
+
+    Raises:
+        RuntimeError: If called from within a running event loop.  Callers
+            inside an async context must ``await`` the coroutine directly.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        raise RuntimeError(
+            "run_async() called from a running event loop — await the coroutine directly instead."
+        )
+    _install_uvloop()
+    try:
+        return asyncio.run(coro)
+    except KeyboardInterrupt:
+        raise
+    except SystemExit:
+        raise
+
+
+async def _async_main(runtime: Any) -> None:
+    """Top-level coroutine: run the interactive REPL session."""
+    from velune.cli.repl import VeluneREPL
+
+    repl = VeluneREPL(runtime)
+    await repl.run()
+
+
+def launch(runtime: Any) -> None:
+    """Start the full interactive Velune session from a synchronous Typer callback.
+
+    Catches ``KeyboardInterrupt`` (Ctrl-C outside the REPL loop) so Typer sees
+    a clean exit.  ``SystemExit`` is re-raised so ``typer.Exit`` works normally.
+    """
+    try:
+        run_async(_async_main(runtime))
+    except KeyboardInterrupt:
+        pass
+    except SystemExit:
+        raise