velune-cli 0.9.0__py3-none-any.whl

velune/context/token_counter.py

@@ -0,0 +1,134 @@
+"""Token counter with model-aware encoding support.
+
+Supports accurate token counting for OpenAI-family models via tiktoken,
+with conservative fallback for other model families.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from velune.core.types.model import ModelDescriptor
+from velune.models.family import ModelFamily, detect_family
+
+logger = logging.getLogger("velune.context.token_counter")
+
+# Attempt to load tiktoken for accurate OpenAI-family token counting
+try:
+    import tiktoken
+
+    HAS_TIKTOKEN = True
+except ImportError:
+    HAS_TIKTOKEN = False
+    logger.warning("tiktoken not available; using heuristic token estimation")
+
+
+class TokenCounter:
+    """Token counting with model-specific encoding support."""
+
+    # Tiktoken encoding registry for OpenAI-family models
+    _ENCODING_CACHE: dict[str, Any] = {}
+
+    @staticmethod
+    def count(text: str, model: ModelDescriptor) -> int:
+        """Count tokens in text for the given model.
+
+        Args:
+            text: Text to count tokens in
+            model: ModelDescriptor with model_id and family information
+
+        Returns:
+            Estimated or exact token count
+        """
+        if not text:
+            return 0
+
+        # Detect model family if not specified
+        family = detect_family(model.model_id)
+
+        # OpenAI-family models: use tiktoken for accuracy
+        if family in (ModelFamily.CLAUDE, ModelFamily.GPT):
+            return TokenCounter._count_openai_family(text, model.model_id)
+
+        # Other families: conservative heuristic
+        return TokenCounter._count_heuristic(text)
+
+    @staticmethod
+    def count_messages(messages: list[dict[str, str]], model: ModelDescriptor) -> int:
+        """Count tokens in a list of messages.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys
+            model: ModelDescriptor for encoding selection
+
+        Returns:
+            Total token count including overhead for message structure
+        """
+        if not messages:
+            return 0
+
+        # Message structure overhead: ~4 tokens per message for role markers
+        structure_overhead = len(messages) * 4
+
+        # Count tokens in all message content
+        content_tokens = sum(TokenCounter.count(msg.get("content", ""), model) for msg in messages)
+
+        return structure_overhead + content_tokens
+
+    @staticmethod
+    def _count_openai_family(text: str, model_id: str) -> int:
+        """Count tokens using tiktoken for OpenAI-family models.
+
+        Falls back to heuristic if tiktoken unavailable.
+        """
+        if not HAS_TIKTOKEN:
+            return TokenCounter._count_heuristic(text)
+
+        try:
+            # Determine appropriate encoding
+            encoding_name = TokenCounter._select_encoding(model_id)
+            if encoding_name not in TokenCounter._ENCODING_CACHE:
+                TokenCounter._ENCODING_CACHE[encoding_name] = tiktoken.get_encoding(encoding_name)
+            encoding = TokenCounter._ENCODING_CACHE[encoding_name]
+
+            # Count tokens, allowing special characters
+            return len(encoding.encode(text, disallowed_special=()))
+        except Exception as e:
+            logger.debug(f"tiktoken counting failed for {model_id}: {e}; falling back to heuristic")
+            return TokenCounter._count_heuristic(text)
+
+    @staticmethod
+    def _count_heuristic(text: str) -> int:
+        """Conservative token estimation for non-OpenAI models.
+
+        Assumes 1 token ≈ 1.35 words (English language average).
+        Used as fallback when tiktoken unavailable or for non-OpenAI models.
+        """
+        if not text:
+            return 0
+        word_count = len(text.split())
+        return max(1, int(word_count * 1.35))
+
+    @staticmethod
+    def _select_encoding(model_id: str) -> str:
+        """Select appropriate tiktoken encoding based on model.
+
+        Args:
+            model_id: Model identifier (e.g., "gpt-4-turbo", "gpt-3.5-turbo")
+
+        Returns:
+            Tiktoken encoding name (e.g., "cl100k_base", "o200k_base")
+        """
+        model_lower = model_id.lower()
+
+        # o1 and newer models: o200k_base
+        if "o1" in model_lower or "o200k" in model_lower:
+            return "o200k_base"
+
+        # GPT-4-turbo and newer: cl100k_base
+        if "gpt-4" in model_lower or "gpt-4-turbo" in model_lower:
+            return "cl100k_base"
+
+        # GPT-3.5 and other models: cl100k_base
+        return "cl100k_base"

velune/context/utilization.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from velune.context.window import estimate_tokens
+
+
+class ContextUtilizationTracker:
+    """Tracks token consumption dynamically and reports utilization percentages."""
+
+    def __init__(self, max_tokens: int = 8192) -> None:
+        self.max_tokens = max_tokens
+        self.used_tokens = 0
+
+    def update(self, conversation: list[dict] | str) -> None:
+        """Update the used token count based on active conversation list or raw string."""
+        if isinstance(conversation, str):
+            self.used_tokens = estimate_tokens(conversation)
+        elif isinstance(conversation, list):
+            text = " ".join(m.get("content", "") for m in conversation if isinstance(m, dict))
+            self.used_tokens = estimate_tokens(text)
+        else:
+            self.used_tokens = 0
+
+    @property
+    def percentage(self) -> float:
+        """Returns the percentage of utilization, from 0.0 to 100.0."""
+        if self.max_tokens <= 0:
+            return 0.0
+        return min((self.used_tokens / self.max_tokens) * 100.0, 100.0)
+
+    @property
+    def formatted_badge(self) -> str:
+        """Returns a string in the format [ctx:NN%]."""
+        return f"[ctx:{self.percentage:.0f}%]"

velune/context/window.py

@@ -0,0 +1,63 @@
+"""Context window and token tracking utilities."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("velune.context.window")
+
+# Attempt to load tiktoken, fallback to heuristic if unavailable
+try:
+    import tiktoken
+
+    _encoding = tiktoken.get_encoding("cl100k_base")
+    HAS_TIKTOKEN = True
+except ImportError:
+    HAS_TIKTOKEN = False
+    _encoding = None
+
+
+def estimate_tokens(text: str) -> int:
+    """Accurately count or estimate tokens in a given text block."""
+    if not text:
+        return 0
+    if HAS_TIKTOKEN and _encoding is not None:
+        try:
+            return len(_encoding.encode(text, disallowed_special=()))
+        except Exception:
+            pass
+    # Fallback heuristic: 1 token is roughly 4 characters
+    return len(text) // 4 + (1 if len(text) % 4 > 0 else 0)
+
+
+class ContextWindowTracker:
+    """Tracks token consumption dynamically against a maximum budget capacity."""
+
+    def __init__(self, max_tokens: int = 8192) -> None:
+        self.max_tokens = max_tokens
+        self.current_tokens = 0
+        self.segments: dict[str, int] = {}
+
+    def reserve(self, segment_name: str, text: str) -> int:
+        """Reserve token budget for a specific context segment."""
+        tokens = estimate_tokens(text)
+        self.segments[segment_name] = tokens
+        self._recalculate()
+        return tokens
+
+    def release(self, segment_name: str) -> None:
+        """Release reservation for a context segment."""
+        self.segments.pop(segment_name, None)
+        self._recalculate()
+
+    def get_remaining(self) -> int:
+        """Get remaining available token budget."""
+        return max(0, self.max_tokens - self.current_tokens)
+
+    def is_overflowed(self) -> bool:
+        """Check if current reservations exceed max tokens."""
+        return self.current_tokens > self.max_tokens
+
+    def _recalculate(self) -> None:
+        self.current_tokens = sum(self.segments.values())
+        logger.debug("Recalculated tokens: %d/%d", self.current_tokens, self.max_tokens)

velune/core/__init__.py

@@ -0,0 +1,89 @@
+"""Foundational primitives and contracts."""
+
+from velune.core.errors import *
+from velune.core.types import *
+from velune.kernel.config import (
+    ConfigLoader,
+    ContextConfig,
+    ExecutionConfig,
+    MemoryConfig,
+    ProjectConfig,
+    ProviderEntry,
+    ProvidersConfig,
+    RetrievalConfig,
+    TelemetryConfig,
+    VeluneConfig,
+    WorkspaceConfig,
+    get_default_config,
+)
+from velune.kernel.registry import ServiceContainer, get_container, inject
+
+__all__ = [
+    # Types
+    "AgentRole",
+    "AgentMessage",
+    "AgentMessageType",
+    "AgentResult",
+    "ContextPriority",
+    "ContextChunk",
+    "ContextWindow",
+    "InferenceRequest",
+    "StreamChunk",
+    "InferenceResponse",
+    "MemoryType",
+    "MemoryRecord",
+    "MemoryQuery",
+    "CapabilityLevel",
+    "ModelCapability",
+    "ModelDescriptor",
+    "ProviderConfig",
+    "ProviderCapabilities",
+    "FileNode",
+    "SymbolNode",
+    "DependencyEdge",
+    "TaskStatus",
+    "Task",
+    "TaskStep",
+    "TaskPlan",
+    "TaskResult",
+    "WorkspaceState",
+    "WorkspaceEvent",
+    # Config
+    "VeluneConfig",
+    "ProjectConfig",
+    "WorkspaceConfig",
+    "ContextConfig",
+    "MemoryConfig",
+    "RetrievalConfig",
+    "ExecutionConfig",
+    "ProviderEntry",
+    "ProvidersConfig",
+    "TelemetryConfig",
+    "ConfigLoader",
+    "get_default_config",
+    # Errors
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderConnectionError",
+    "ProviderAuthenticationError",
+    "ModelNotFoundError",
+    "InferenceError",
+    "OrchestrationError",
+    "AgentExecutionError",
+    "PipelineExecutionError",
+    "StateTransitionError",
+    "CheckpointError",
+    "VeluneMemoryError",
+    "VeluneMemoryStoreError",
+    "VeluneMemoryRetrievalError",
+    "VeluneMemoryConsolidationError",
+    "ExecutionError",
+    "SandboxError",
+    "SnapshotError",
+    "RollbackError",
+    "ValidationError",
+    # Registry
+    "ServiceContainer",
+    "inject",
+    "get_container",
+]

velune/core/background.py

@@ -0,0 +1,5 @@
+"""Re-export BackgroundTaskRegistry under the canonical background module path."""
+
+from velune.core.task_registry import BackgroundTaskRegistry
+
+__all__ = ["BackgroundTaskRegistry"]

velune/core/config/__init__.py

@@ -0,0 +1,37 @@
+"""Configuration management re-exported from velune.kernel.config."""
+
+from __future__ import annotations
+
+from velune.kernel.config import (
+    ConfigLoader,
+    ConfigService,
+    ContextConfig,
+    ExecutionConfig,
+    MCPConfig,
+    MemoryConfig,
+    ProjectConfig,
+    ProviderEntry,
+    ProvidersConfig,
+    RetrievalConfig,
+    TelemetryConfig,
+    VeluneConfig,
+    WorkspaceConfig,
+    get_default_config,
+)
+
+__all__ = [
+    "VeluneConfig",
+    "ProjectConfig",
+    "WorkspaceConfig",
+    "ContextConfig",
+    "MemoryConfig",
+    "RetrievalConfig",
+    "ExecutionConfig",
+    "ProviderEntry",
+    "ProvidersConfig",
+    "TelemetryConfig",
+    "MCPConfig",
+    "ConfigLoader",
+    "ConfigService",
+    "get_default_config",
+]

velune/core/errors/__init__.py

@@ -0,0 +1,90 @@
+"""Typed error hierarchy."""
+
+from velune.core.errors.catalog import (
+    APIKeyMissingError,
+    ContextWindowExceededError,
+    IndexingFailedError,
+    InsufficientVRAMError,
+    NoModelsAvailableError,
+    OllamaNotRunningError,
+    ProviderUnavailableError,
+    RateLimitError,
+    SSRFAttemptError,
+    VeluneError,
+    WorkspaceNotInitializedError,
+)
+from velune.core.errors.catalog import (
+    ModelNotFoundError as ModelNotFoundVeluneError,
+)
+from velune.core.errors.catalog import (
+    PathTraversalError as PathTraversalVeluneError,
+)
+from velune.core.errors.execution import (
+    ExecutionError,
+    RollbackError,
+    SandboxError,
+    SnapshotError,
+    ValidationError,
+)
+from velune.core.errors.memory import (
+    VeluneMemoryConsolidationError,
+    VeluneMemoryError,
+    VeluneMemoryRetrievalError,
+    VeluneMemoryStoreError,
+)
+from velune.core.errors.orchestration import (
+    AgentExecutionError,
+    CheckpointError,
+    OrchestrationError,
+    PipelineExecutionError,
+    StateTransitionError,
+)
+from velune.core.errors.provider import (
+    InferenceError,
+    ModelNotFoundError,
+    ProviderAuthenticationError,
+    ProviderConnectionError,
+    ProviderError,
+    ProviderNotFoundError,
+)
+
+__all__ = [
+    # User-facing catalog errors
+    "VeluneError",
+    "OllamaNotRunningError",
+    "ModelNotFoundVeluneError",
+    "NoModelsAvailableError",
+    "APIKeyMissingError",
+    "WorkspaceNotInitializedError",
+    "ProviderUnavailableError",
+    "ContextWindowExceededError",
+    "RateLimitError",
+    "InsufficientVRAMError",
+    "PathTraversalVeluneError",
+    "SSRFAttemptError",
+    "IndexingFailedError",
+    # Internal provider errors
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderConnectionError",
+    "ProviderAuthenticationError",
+    "ModelNotFoundError",
+    "InferenceError",
+    # Internal orchestration errors
+    "OrchestrationError",
+    "AgentExecutionError",
+    "PipelineExecutionError",
+    "StateTransitionError",
+    "CheckpointError",
+    # Internal memory errors
+    "VeluneMemoryError",
+    "VeluneMemoryStoreError",
+    "VeluneMemoryRetrievalError",
+    "VeluneMemoryConsolidationError",
+    # Internal execution errors
+    "ExecutionError",
+    "SandboxError",
+    "SnapshotError",
+    "RollbackError",
+    "ValidationError",
+]

velune/core/errors/catalog.py

@@ -0,0 +1,188 @@
+"""Structured user-facing error catalog.
+
+Every error type carries a short title, a cause explanation, and actionable
+fix steps.  The CLI renders these via ``velune.cli.rendering.error_panel``
+instead of printing raw exception text.
+"""
+
+from __future__ import annotations
+
+
+class VeluneError(Exception):
+    """Base class for all user-facing Velune errors with rich display metadata.
+
+    Subclasses declare ``title``, ``cause``, ``fix``, and optionally
+    ``docs_url`` as class attributes.  The ``__init__`` accepts an optional
+    *detail* string (e.g. the underlying exception message) and an optional
+    *cause_override* to substitute the class-level ``cause`` at runtime when
+    the root cause is known precisely.
+    """
+
+    title: str = "An unexpected error occurred"
+    cause: str = "An internal error was encountered."
+    fix: list[str] = ["Run `velune doctor` to diagnose your environment."]
+    docs_url: str | None = None
+
+    def __init__(
+        self,
+        detail: str | None = None,
+        *,
+        cause_override: str | None = None,
+    ) -> None:
+        self._detail = detail
+        self._cause_override = cause_override
+        super().__init__(detail or self.title)
+
+    def get_cause(self) -> str:
+        return self._cause_override or self.cause
+
+    def get_detail(self) -> str | None:
+        return self._detail
+
+
+# ---------------------------------------------------------------------------
+# Provider / model errors
+# ---------------------------------------------------------------------------
+
+
+class OllamaNotRunningError(VeluneError):
+    title = "Ollama is not running"
+    cause = "Velune tried to connect to Ollama at localhost:11434 but the connection was refused."
+    fix = [
+        "Run `ollama serve` in a separate terminal window",
+        "Then retry your command, or run `velune doctor` to verify all providers",
+    ]
+
+
+class ModelNotFoundError(VeluneError):
+    title = "Model not found"
+    cause = "The requested model ID is not registered in the Velune model catalog."
+    fix = [
+        "Run `velune models scan` to discover available models",
+        "Check the model ID for typos",
+        "Run `velune models list` to see all registered models",
+    ]
+
+
+class NoModelsAvailableError(VeluneError):
+    title = "No models available"
+    cause = "No models are configured for any provider in this workspace."
+    fix = [
+        "Run `velune models scan` to discover local Ollama models",
+        "Configure an API key with `velune config set providers.anthropic.api_key <key>`",
+        "Run `velune doctor` to diagnose provider connectivity",
+    ]
+
+
+class APIKeyMissingError(VeluneError):
+    title = "API key missing"
+    cause = (
+        "A cloud provider is configured but no API key was found in the environment or keystore."
+    )
+    fix = [
+        "Set the API key with `velune config set providers.<name>.api_key <key>`",
+        "Or export it as an environment variable (e.g. ANTHROPIC_API_KEY=...)",
+        "Run `velune doctor` to see which providers are missing keys",
+    ]
+
+
+class ProviderUnavailableError(VeluneError):
+    title = "Provider unavailable"
+    cause = "The model provider failed its health check and cannot accept inference requests."
+    fix = [
+        "Run `velune doctor check` to identify which providers are unreachable",
+        "Verify the provider service is running (e.g. `ollama serve` for Ollama)",
+        "Check API key and network connectivity for cloud providers",
+    ]
+
+
+class RateLimitError(VeluneError):
+    title = "Rate limit reached"
+    cause = "The cloud provider has temporarily limited requests from this API key."
+    fix = [
+        "Wait a moment and retry the command",
+        "Use a local model (Ollama) as a fallback to avoid rate limits",
+        "Check your provider's dashboard for quota and usage details",
+    ]
+
+
+class ContextWindowExceededError(VeluneError):
+    title = "Context window exceeded"
+    cause = "The combined prompt and context is larger than the model's maximum context length."
+    fix = [
+        "Use a model with a larger context window (`velune models list`)",
+        "Reduce the amount of repository context by narrowing the file selection",
+        "Split the task into smaller, focused sub-tasks",
+    ]
+
+
+class InsufficientVRAMError(VeluneError):
+    title = "Insufficient VRAM"
+    cause = "The selected local model requires more GPU memory than is currently available."
+    fix = [
+        "Close other GPU-intensive applications to free VRAM",
+        "Use a smaller quantized version of the model (e.g. q4_K_M instead of q8_0)",
+        "Run `velune doctor` to view your hardware profile and compatible models",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Workspace / configuration errors
+# ---------------------------------------------------------------------------
+
+
+class WorkspaceNotInitializedError(VeluneError):
+    title = "Workspace not initialized"
+    cause = "This directory does not contain a Velune workspace (velune.toml not found)."
+    fix = [
+        "Run `velune workspace init` to initialize this directory as a Velune workspace",
+        "Or change to a directory that already contains a velune.toml",
+        "Use `--workspace <path>` to point to an existing workspace",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Security errors
+# ---------------------------------------------------------------------------
+
+
+class PathTraversalError(VeluneError):
+    title = "Path traversal blocked"
+    cause = (
+        "A file path resolved to a location outside the workspace root. "
+        "This is a security violation."
+    )
+    fix = [
+        "Ensure all file paths are relative to the workspace root",
+        "Do not use `..` sequences or absolute paths that escape the workspace",
+        "Run `velune workspace info` to confirm your current workspace root",
+    ]
+
+
+class SSRFAttemptError(VeluneError):
+    title = "Internal network request blocked"
+    cause = (
+        "A web tool attempted to reach an internal or metadata network address "
+        "(e.g. cloud provider IMDS, RFC 1918 private ranges). "
+        "This request was blocked to prevent SSRF attacks."
+    )
+    fix = [
+        "Only fetch publicly accessible URLs",
+        "Avoid internal network addresses (169.254.x.x, 10.x.x.x, 192.168.x.x, etc.)",
+        "If this was unexpected, inspect workspace content for injected URLs",
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Repository / indexing errors
+# ---------------------------------------------------------------------------
+
+
+class IndexingFailedError(VeluneError):
+    title = "Repository indexing failed"
+    cause = "Velune encountered an error while indexing the repository AST and structure."
+    fix = [
+        "Run `velune workspace reindex` to force a fresh index",
+        "Check file permissions in the workspace directory",
+        "Run `velune doctor` to verify the workspace is correctly configured",
+    ]

velune/core/errors/execution.py

@@ -0,0 +1,31 @@
+"""Execution-related errors."""
+
+
+class ExecutionError(Exception):
+    """Base exception for execution errors."""
+
+    pass
+
+
+class SandboxError(ExecutionError):
+    """Raised when sandbox operation fails."""
+
+    pass
+
+
+class SnapshotError(ExecutionError):
+    """Raised when snapshot operation fails."""
+
+    pass
+
+
+class RollbackError(ExecutionError):
+    """Raised when rollback operation fails."""
+
+    pass
+
+
+class ValidationError(ExecutionError):
+    """Raised when validation fails."""
+
+    pass