velune-cli 0.9.0__py3-none-any.whl

velune/core/errors/memory.py

@@ -0,0 +1,25 @@
+"""Memory-related errors."""
+
+
+class VeluneMemoryError(Exception):
+    """Base exception for memory errors."""
+
+    pass
+
+
+class VeluneMemoryStoreError(VeluneMemoryError):
+    """Raised when memory store operation fails."""
+
+    pass
+
+
+class VeluneMemoryRetrievalError(VeluneMemoryError):
+    """Raised when memory retrieval fails."""
+
+    pass
+
+
+class VeluneMemoryConsolidationError(VeluneMemoryError):
+    """Raised when memory consolidation fails."""
+
+    pass

velune/core/errors/orchestration.py

@@ -0,0 +1,31 @@
+"""Orchestration-related errors."""
+
+
+class OrchestrationError(Exception):
+    """Base exception for orchestration errors."""
+
+    pass
+
+
+class AgentExecutionError(OrchestrationError):
+    """Raised when agent execution fails."""
+
+    pass
+
+
+class PipelineExecutionError(OrchestrationError):
+    """Raised when pipeline execution fails."""
+
+    pass
+
+
+class StateTransitionError(OrchestrationError):
+    """Raised when state transition fails."""
+
+    pass
+
+
+class CheckpointError(OrchestrationError):
+    """Raised when checkpoint operation fails."""
+
+    pass

velune/core/errors/provider.py

@@ -0,0 +1,37 @@
+"""Provider-related errors."""
+
+
+class ProviderError(Exception):
+    """Base exception for provider errors."""
+
+    pass
+
+
+class ProviderNotFoundError(ProviderError):
+    """Raised when a provider is not found."""
+
+    pass
+
+
+class ProviderConnectionError(ProviderError):
+    """Raised when connection to provider fails."""
+
+    pass
+
+
+class ProviderAuthenticationError(ProviderError):
+    """Raised when provider authentication fails."""
+
+    pass
+
+
+class ModelNotFoundError(ProviderError):
+    """Raised when a model is not found."""
+
+    pass
+
+
+class InferenceError(ProviderError):
+    """Raised when inference fails."""
+
+    pass

velune/core/event_loop.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def get_loop() -> asyncio.AbstractEventLoop:
+    """Return the running event loop, or a freshly created one."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.new_event_loop()
+
+
+def submit(coro: Coroutine[Any, Any, T]) -> T:
+    """Run *coro* to completion from a synchronous call site.
+
+    Raises RuntimeError if called from within a running event loop — callers
+    inside an async context should await the coroutine directly.
+
+    Delegates to ``velune.kernel.entrypoint.run_async`` so that
+    ``asyncio.run`` is called from exactly one place in the codebase.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        from velune.kernel.entrypoint import run_async
+
+        return run_async(coro)
+    raise RuntimeError(
+        "submit() called from a running event loop — await the coroutine directly instead."
+    )

velune/core/logging.py

@@ -0,0 +1,83 @@
+"""Logging configuration for Velune."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import warnings
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from rich.logging import RichHandler
+
+from velune.core.trace import TracedLogger, _agent_id, _run_id, _step_id
+
+
+class JsonFormatter(logging.Formatter):
+    """Production JSON log formatter that extracts context tracing attributes."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        exc_info = None
+        if record.exc_info:
+            exc_info = self.formatException(record.exc_info)
+
+        ts = datetime.now(UTC).isoformat().replace("+00:00", "")
+
+        log_data = {
+            "ts": ts,
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            "run_id": _run_id.get(),
+            "agent_id": _agent_id.get(),
+            "step_id": _step_id.get(),
+        }
+        if exc_info:
+            log_data["exception"] = exc_info
+
+        return json.dumps(log_data)
+
+
+@dataclass(frozen=True)
+class LoggingConfig:
+    """Logging configuration used during CLI bootstrap."""
+
+    level: str = "INFO"
+    show_path: bool = False
+    rich_tracebacks: bool = True
+
+
+def configure_logging(config: LoggingConfig) -> None:
+    """Configure process-wide logging once at startup."""
+
+    log_format = os.environ.get("VELUNE_LOG_FORMAT", "").lower()
+
+    if log_format == "json":
+        handler = logging.StreamHandler()
+        handler.setFormatter(JsonFormatter())
+        handlers: list[logging.Handler] = [handler]
+    else:
+        handlers = [
+            RichHandler(
+                rich_tracebacks=config.rich_tracebacks,
+                show_path=config.show_path,
+                omit_repeated_times=False,
+            )
+        ]
+
+    logging.basicConfig(
+        level=getattr(logging, config.level.upper(), logging.INFO),
+        format="%(message)s" if log_format != "json" else None,
+        datefmt="[%X]" if log_format != "json" else None,
+        handlers=handlers,
+        force=True,
+    )
+    logging.captureWarnings(True)
+    warnings.simplefilter("default")
+
+
+def get_logger(name: str) -> TracedLogger:
+    """Get a namespaced Velune logger."""
+
+    return TracedLogger(name)

velune/core/paths.py

@@ -0,0 +1,165 @@
+"""Platform-compliant storage paths for Velune.
+
+Heavy, frequently-written state (the SQLite cognitive core and the Qdrant
+vector store) must NOT live inside the workspace tree. On Windows the
+workspace is often under a cloud-synced folder (OneDrive, Dropbox, Google
+Drive). Every file touch then triggers a sync-engine reparse, multiplying
+I/O latency by 3-10x and serializing startup behind metadata syncs. This was
+the dominant contributor to Velune's ~78s cold start.
+
+This module centralizes storage resolution so all subsystems agree on one
+location, and relocates heavy state to the platform-native, *non-synced*
+application-data directory:
+
+    Windows  -> %LOCALAPPDATA%\\Velune
+    macOS    -> ~/Library/Application Support/Velune
+    Linux    -> $XDG_DATA_HOME/velune  (default ~/.local/share/velune)
+
+State is still isolated *per workspace* (so two projects never share a
+cognitive core) by hashing the workspace's resolved absolute path into a
+stable, human-readable slug under ``<data_root>/workspaces/``.
+
+Lightweight, human-facing files (``velune.toml``, ``.veluneignore``,
+snapshots, sessions) intentionally stay in the workspace ``.velune/`` dir —
+they're tiny, rarely written, and users expect them project-local.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import platform
+import re
+import shutil
+from pathlib import Path
+
+logger = logging.getLogger("velune.core.paths")
+
+_APP_NAME = "Velune"
+
+# Heavy state filenames relocated off the workspace tree.
+COGNITIVE_DB_NAME = "velune_cognitive_core.db"
+QDRANT_STORE_NAME = "qdrant_local_store"
+
+# Marker written into a relocated workspace dir once legacy data has been
+# migrated, so migration runs at most once per workspace.
+_MIGRATION_MARKER = ".migrated_from_workspace"
+
+
+def app_data_root() -> Path:
+    """Return the platform-native, non-synced application data root.
+
+    Honors ``VELUNE_DATA_HOME`` as an explicit override (useful for tests,
+    CI, and power users who want all state in one place).
+    """
+    override = os.environ.get("VELUNE_DATA_HOME")
+    if override:
+        return Path(override).expanduser()
+
+    system = platform.system()
+    if system == "Windows":
+        base = os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local")
+        return Path(base) / _APP_NAME
+    if system == "Darwin":
+        return Path.home() / "Library" / "Application Support" / _APP_NAME
+    # Linux / other POSIX
+    xdg = os.environ.get("XDG_DATA_HOME")
+    base = Path(xdg) if xdg else (Path.home() / ".local" / "share")
+    return base / "velune"
+
+
+def _workspace_slug(workspace: Path) -> str:
+    """Build a stable, collision-resistant, readable slug for *workspace*.
+
+    Combines a sanitized directory name with a short hash of the resolved
+    absolute path so distinct projects with the same folder name never
+    collide.
+    """
+    try:
+        resolved = workspace.resolve()
+    except Exception:
+        resolved = workspace.absolute()
+    digest = hashlib.sha1(str(resolved).encode("utf-8")).hexdigest()[:10]
+    name = re.sub(r"[^A-Za-z0-9._-]", "_", resolved.name) or "workspace"
+    return f"{name}-{digest}"
+
+
+def workspace_storage_dir(workspace: Path) -> Path:
+    """Return (creating) the non-synced storage dir for *workspace*."""
+    target = app_data_root() / "workspaces" / _workspace_slug(workspace)
+    target.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def cognitive_db_path(workspace: Path) -> Path:
+    """Absolute path to the workspace's SQLite cognitive core (non-synced)."""
+    return workspace_storage_dir(workspace) / COGNITIVE_DB_NAME
+
+
+def qdrant_store_path(workspace: Path) -> Path:
+    """Absolute path to the workspace's Qdrant local store (non-synced)."""
+    return workspace_storage_dir(workspace) / QDRANT_STORE_NAME
+
+
+LANCEDB_STORE_NAME = "lancedb_semantic_store"
+
+
+def lancedb_store_path(workspace: Path) -> Path:
+    """Absolute path to the workspace's LanceDB semantic store (non-synced)."""
+    return workspace_storage_dir(workspace) / LANCEDB_STORE_NAME
+
+
+def legacy_workspace_dir(workspace: Path) -> Path:
+    """The old in-workspace ``.velune`` directory (may be cloud-synced)."""
+    return workspace / ".velune"
+
+
+def migrate_legacy_storage(workspace: Path) -> bool:
+    """One-time, best-effort relocation of heavy state out of the workspace.
+
+    Copies (does not move) any pre-existing ``.velune/velune_cognitive_core.db``
+    and ``.velune/qdrant_local_store`` into the non-synced storage dir, leaving
+    the originals untouched as a safety backup. Writes a marker so this runs at
+    most once per workspace. Returns True if anything was migrated.
+
+    Copy-then-mark (rather than move) is deliberate: an interrupted move could
+    corrupt a live cognitive core, whereas a partial copy is simply retried.
+    """
+    target = workspace_storage_dir(workspace)
+    marker = target / _MIGRATION_MARKER
+    if marker.exists():
+        return False
+
+    legacy = legacy_workspace_dir(workspace)
+    migrated = False
+
+    legacy_db = legacy / COGNITIVE_DB_NAME
+    new_db = target / COGNITIVE_DB_NAME
+    if legacy_db.exists() and not new_db.exists():
+        try:
+            # Bring along WAL/SHM sidecars if present for a consistent copy.
+            for suffix in ("", "-wal", "-shm"):
+                src = legacy / f"{COGNITIVE_DB_NAME}{suffix}"
+                if src.exists():
+                    shutil.copy2(src, target / src.name)
+            migrated = True
+            logger.info("Migrated cognitive core from %s -> %s", legacy_db, new_db)
+        except Exception as exc:
+            logger.warning("Cognitive core migration skipped: %s", exc)
+
+    legacy_qdrant = legacy / QDRANT_STORE_NAME
+    new_qdrant = target / QDRANT_STORE_NAME
+    if legacy_qdrant.is_dir() and not new_qdrant.exists():
+        try:
+            shutil.copytree(legacy_qdrant, new_qdrant)
+            migrated = True
+            logger.info("Migrated vector store from %s -> %s", legacy_qdrant, new_qdrant)
+        except Exception as exc:
+            logger.warning("Vector store migration skipped: %s", exc)
+
+    try:
+        marker.write_text("ok\n", encoding="utf-8")
+    except Exception:
+        pass
+    return migrated

velune/core/runtime.py

@@ -0,0 +1,113 @@
+"""Process runtime bootstrap for Velune Cognitive OS CLI."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+
+from velune.kernel.config import ConfigService, VeluneConfig, get_default_config
+from velune.kernel.lifecycle import LifecycleCoordinator
+from velune.kernel.registry import ServiceContainer
+
+# Stateful Orchestration & Memory Tiers
+
+
+@dataclass(slots=True)
+class RuntimeContext:
+    """Runtime resources shared across CLI commands."""
+
+    workspace: Path
+    config_path: Path | None
+    config: VeluneConfig
+    console: Console
+    logger_name: str
+    container: ServiceContainer
+
+
+def build_runtime(
+    workspace: Path,
+    config_path: Path | None = None,
+    verbose: bool = False,
+) -> RuntimeContext:
+    """Create and register the shared runtime services using the declarative bootstrapper."""
+    from velune.core.startup_profiler import mark
+
+    mark("build_runtime: enter")
+    # 1. Setup Logging and Console
+    console = Console(highlight=False)
+    logger_name = "velune"
+    logger = logging.getLogger(logger_name)
+
+    # Configure root logger levels. Non-verbose hides internal INFO/DEBUG
+    # logs so users only ever see Rich-formatted output, not raw Python logs.
+    logging.basicConfig(level=logging.DEBUG if verbose else logging.WARNING)
+    logger.setLevel(logging.DEBUG if verbose else logging.WARNING)
+
+    # 2. Configuration Service
+    config_service = ConfigService(workspace=workspace, config_path=config_path)
+    try:
+        config = config_service.load()
+    except Exception as e:
+        logger.warning("Failed to load configuration. Falling back to system defaults: %s", e)
+        config = get_default_config()
+    mark("config loaded")
+
+    container = ServiceContainer()
+    lifecycle = LifecycleCoordinator()
+    lifecycle.container = container
+
+    # Pre-register basic primitive context dependencies
+    container.register_instance("runtime.config", config)
+    container.register_instance("runtime.config_service", config_service)
+    container.register_instance("runtime.console", console)
+    container.register_instance("runtime.logger", logger)
+    container.register_instance("runtime.workspace", workspace)
+    container.register_instance("runtime.config_path", config_path)
+    container.register_instance("runtime.lifecycle", lifecycle)
+
+    # Detect and persist GPU info
+    try:
+        from velune.providers.discovery.gpu import GPUDetector
+
+        gpu_info = GPUDetector().detect()
+    except Exception as e:
+        logger.warning("GPU detection failed, using safe defaults: %s", e)
+        gpu_info = {
+            "has_gpu": False,
+            "gpu_type": None,
+            "vram_total_gb": None,
+            "vram_free_gb": None,
+            "cuda_available": False,
+        }
+    container.register_instance("runtime.gpu_info", gpu_info)
+    mark("gpu detected")
+
+    # 3. Initialize and bootstrap declarative subsystems in dependency order
+    from velune.kernel.bootstrap import RuntimeBootstrapper, RuntimeEnvironment
+    from velune.kernel.modules import ALL_MODULES
+
+    env = RuntimeEnvironment(
+        workspace=workspace,
+        config=config,
+        container=container,
+        lifecycle=lifecycle,
+        verbose=verbose,
+    )
+
+    bootstrapper = RuntimeBootstrapper()
+    for module in ALL_MODULES:
+        bootstrapper.register_module(module)
+    bootstrapper.bootstrap(env)
+    mark("subsystems bootstrapped")
+
+    return RuntimeContext(
+        workspace=workspace,
+        config_path=config_path,
+        config=config,
+        console=console,
+        logger_name=logger_name,
+        container=container,
+    )

velune/core/startup_profiler.py

@@ -0,0 +1,56 @@
+"""Lightweight startup phase profiler.
+
+Enable with ``VELUNE_PROFILE_STARTUP=1`` to print a per-phase timing breakdown
+of the boot path to stderr. Each ``mark()`` prints immediately (with the delta
+since the previous mark), so the breakdown survives even if startup crashes
+mid-phase — invaluable for diagnosing where the time goes on a given machine.
+
+Zero overhead when disabled: ``mark()`` short-circuits on the first line.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import sys
+import time
+
+_ENABLED = os.environ.get("VELUNE_PROFILE_STARTUP", "").lower() in ("1", "true", "yes")
+_PROCESS_START = time.perf_counter()
+_marks: list[tuple[str, float]] = []
+_reported = False
+
+
+def enabled() -> bool:
+    return _ENABLED
+
+
+def mark(label: str) -> None:
+    """Record and print a startup phase boundary (no-op unless enabled)."""
+    if not _ENABLED:
+        return
+    now = time.perf_counter()
+    prev = _marks[-1][1] if _marks else _PROCESS_START
+    _marks.append((label, now))
+    delta = now - prev
+    elapsed = now - _PROCESS_START
+    print(
+        f"[velune startup] +{elapsed:6.3f}s  Δ{delta:6.3f}s  {label}",
+        file=sys.stderr,
+        flush=True,
+    )
+
+
+def report() -> None:
+    """Print a final total. Registered via atexit; safe to call directly."""
+    global _reported
+    if not _ENABLED or _reported:
+        return
+    _reported = True
+    total = time.perf_counter() - _PROCESS_START
+    print(f"[velune startup] ── total {total:.3f}s ──", file=sys.stderr, flush=True)
+
+
+if _ENABLED:
+    atexit.register(report)
+    mark("interpreter -> profiler import")

velune/core/task_registry.py

@@ -0,0 +1,117 @@
+"""Structured concurrency manager for tracking, timing out, and cancelling background tasks."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+logger = logging.getLogger("velune.core.task_registry")
+
+
+class BackgroundTaskRegistry:
+    """Tracks in-flight asyncio tasks with timeout and cancellation support."""
+
+    def __init__(self) -> None:
+        self._tasks: dict[str, asyncio.Task] = {}
+        self._lock = threading.Lock()
+        self._submitted_count = 0
+        self._dropped_count = 0
+
+    def submit(
+        self,
+        name: str,
+        coro: Awaitable[T],
+        timeout_seconds: float = 60.0,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> asyncio.Task | None:
+        """Submit a named background task from an async context only."""
+        try:
+            running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            logger.error(
+                "BackgroundTaskRegistry.submit('%s') called outside an async context. "
+                "Background tasks must be submitted from within a running event loop.",
+                name,
+            )
+            with self._lock:
+                self._dropped_count += 1
+            return None
+
+        with self._lock:
+            self._submitted_count += 1
+
+        async def _wrapped() -> Any:
+            try:
+                result = await asyncio.wait_for(coro, timeout=timeout_seconds)
+                logger.debug("Background task '%s' completed.", name)
+                return result
+            except TimeoutError:
+                logger.warning("Background task '%s' timed out after %.1fs", name, timeout_seconds)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                logger.error("Background task '%s' failed: %s", name, exc)
+                if on_error:
+                    try:
+                        on_error(exc)
+                    except Exception as inner:
+                        logger.error("Error handler for task '%s' failed: %s", name, inner)
+            finally:
+                with self._lock:
+                    self._tasks.pop(name, None)
+
+        task = running_loop.create_task(_wrapped(), name=name)
+        with self._lock:
+            self._tasks[name] = task
+        return task
+
+    async def cancel_all(self, timeout: float = 5.0) -> None:
+        """Cancel all pending tasks and wait for completion."""
+        with self._lock:
+            tasks = [t for t in self._tasks.values() if not t.done()]
+
+        if not tasks:
+            return
+
+        for task in tasks:
+            task.cancel()
+
+        # Give tasks a chance to handle CancelledError
+        done, pending = await asyncio.wait(tasks, timeout=timeout)
+
+        if pending:
+            logger.warning("%d background tasks did not cancel within %.1fs", len(pending), timeout)
+
+        # Shutdown stats reporting of dropped tasks
+        stats = self.stats()
+        if stats["dropped"] > 0:
+            logger.info("Task registry shutdown: %d dropped tasks reported.", stats["dropped"])
+
+        with self._lock:
+            self._tasks.clear()
+
+    def pending_count(self) -> int:
+        """Expose pending tasks count for health checks."""
+        with self._lock:
+            return len([t for t in self._tasks.values() if not t.done()])
+
+    def is_healthy(self) -> bool:
+        """Check if task registry is healthy."""
+        try:
+            loop = asyncio.get_running_loop()
+            loop_alive = loop.is_running()
+        except Exception:
+            loop_alive = False
+        return loop_alive and self.pending_count() < 50
+
+    def stats(self) -> dict[str, int]:
+        """Return task submission telemetry stats."""
+        with self._lock:
+            return {
+                "submitted": self._submitted_count,
+                "dropped": self._dropped_count,
+            }