velune-cli 0.9.0__py3-none-any.whl

velune/core/trace.py

@@ -0,0 +1,83 @@
+"""Structured tracing utilities for distributed execution and agent deliberation in Velune."""
+
+import contextvars
+import logging
+from typing import Any
+
+_run_id: contextvars.ContextVar[str | None] = contextvars.ContextVar("run_id", default=None)
+_agent_id: contextvars.ContextVar[str | None] = contextvars.ContextVar("agent_id", default=None)
+_step_id: contextvars.ContextVar[str | None] = contextvars.ContextVar("step_id", default=None)
+
+
+class TraceContext:
+    """Context manager to manage the active run, agent, and step trace ids in context variables."""
+
+    def __init__(
+        self, run_id: str, agent_id: str | None = None, step_id: str | None = None
+    ) -> None:
+        self._tokens: list[contextvars.Token[str | None]] = []
+        self.run_id = run_id
+        self.agent_id = agent_id
+        self.step_id = step_id
+
+    def __enter__(self) -> "TraceContext":
+        self._tokens = [
+            _run_id.set(self.run_id),
+            _agent_id.set(self.agent_id),
+            _step_id.set(self.step_id),
+        ]
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        for tok in self._tokens:
+            tok.var.reset(tok)
+
+
+def get_trace_prefix() -> str:
+    """Generate the structured trace prefix string from active context variables."""
+    import os
+
+    if os.environ.get("VELUNE_LOG_FORMAT", "").lower() == "json":
+        return ""
+    parts = []
+    if r := _run_id.get():
+        parts.append(f"run={r[:8]}")
+    if a := _agent_id.get():
+        parts.append(f"agent={a}")
+    if s := _step_id.get():
+        parts.append(f"step={s}")
+    return "[" + " ".join(parts) + "] " if parts else ""
+
+
+class TracedLogger:
+    """Logger wrapper that prepends trace context to all messages."""
+
+    def __init__(self, name: str | logging.Logger) -> None:
+        if isinstance(name, str):
+            self._logger = logging.getLogger(name)
+        else:
+            self._logger = name
+
+    def info(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.info(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def warning(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.warning(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def error(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.error(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def debug(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.debug(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def exception(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.exception(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def critical(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.critical(get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def log(self, level: int, msg: Any, *args: Any, **kwargs: Any) -> None:
+        self._logger.log(level, get_trace_prefix() + str(msg), *args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._logger, name)

velune/core/types/__init__.py

@@ -0,0 +1,48 @@
+"""Core type definitions."""
+
+from velune.core.types.agent import AgentMessage, AgentMessageType, AgentResult, AgentRole
+from velune.core.types.context import ContextChunk, ContextPriority, ContextWindow
+from velune.core.types.inference import InferenceRequest, InferenceResponse, StreamChunk
+from velune.core.types.memory import MemoryQuery, MemoryRecord, MemoryType
+from velune.core.types.model import (
+    CapabilityLevel,
+    ModelCapability,
+    ModelCapabilityProfile,
+    ModelDescriptor,
+)
+from velune.core.types.provider import ProviderCapabilities, ProviderConfig
+from velune.core.types.repository import DependencyEdge, FileNode, SymbolNode
+from velune.core.types.task import Task, TaskPlan, TaskResult, TaskStatus, TaskStep
+from velune.core.types.workspace import WorkspaceEvent, WorkspaceState
+
+__all__ = [
+    "AgentRole",
+    "AgentMessage",
+    "AgentMessageType",
+    "AgentResult",
+    "ContextPriority",
+    "ContextChunk",
+    "ContextWindow",
+    "InferenceRequest",
+    "StreamChunk",
+    "InferenceResponse",
+    "MemoryType",
+    "MemoryRecord",
+    "MemoryQuery",
+    "CapabilityLevel",
+    "ModelCapability",
+    "ModelCapabilityProfile",
+    "ModelDescriptor",
+    "ProviderConfig",
+    "ProviderCapabilities",
+    "FileNode",
+    "SymbolNode",
+    "DependencyEdge",
+    "TaskStatus",
+    "Task",
+    "TaskStep",
+    "TaskPlan",
+    "TaskResult",
+    "WorkspaceState",
+    "WorkspaceEvent",
+]

velune/core/types/agent.py

@@ -0,0 +1,53 @@
+"""Core agent type definitions."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AgentRole(StrEnum):
+    """Agent role definitions."""
+
+    PLANNER = "planner"
+    CODER = "coder"
+    REASONER = "reasoner"
+    REVIEWER = "reviewer"
+    DEBUGGER = "debugger"
+    SUMMARIZER = "summarizer"
+    RETRIEVER = "retriever"
+    SUPERVISOR = "supervisor"
+
+
+class AgentMessageType(StrEnum):
+    """Typed message protocol for agent communication."""
+
+    TASK_REQUEST = "task_request"
+    TASK_RESPONSE = "task_response"
+    STATUS_UPDATE = "status_update"
+    ERROR_REPORT = "error_report"
+    QUERY = "query"
+    RESPONSE = "response"
+    CONTROL = "control"
+
+
+class AgentMessage(BaseModel):
+    """Typed message for inter-agent communication."""
+
+    message_type: AgentMessageType
+    sender: str
+    recipient: str
+    content: Any
+    timestamp: float
+    correlation_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentResult(BaseModel):
+    """Result from agent execution."""
+
+    success: bool
+    output: Any | None = None
+    error: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    execution_time_ms: float | None = None

velune/core/types/context.py

@@ -0,0 +1,42 @@
+"""Core context type definitions."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ContextPriority(StrEnum):
+    """Context chunk priority levels."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class ContextChunk(BaseModel):
+    """A chunk of context with metadata."""
+
+    content: str
+    source: str
+    priority: ContextPriority
+    tokens: int
+    relevance_score: float = Field(ge=0.0, le=1.0)
+    timestamp: float
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContextWindow(BaseModel):
+    """The assembled context window for inference."""
+
+    chunks: list[ContextChunk]
+    total_tokens: int
+    max_tokens: int
+    compression_ratio: float = Field(ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def utilization(self) -> float:
+        """Calculate context window utilization."""
+        return self.total_tokens / self.max_tokens if self.max_tokens > 0 else 0.0

velune/core/types/inference.py

@@ -0,0 +1,38 @@
+"""Core inference type definitions."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class InferenceRequest(BaseModel):
+    """Request for model inference."""
+
+    model_id: str
+    messages: list[dict[str, str]]
+    temperature: float = Field(default=0.7, ge=0.0, le=2.0)
+    max_tokens: int | None = None
+    top_p: float = Field(default=1.0, ge=0.0, le=1.0)
+    stop_sequences: list[str] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class StreamChunk(BaseModel):
+    """A chunk of streamed inference response."""
+
+    content: str
+    finish_reason: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InferenceResponse(BaseModel):
+    """Response from model inference."""
+
+    content: str
+    model_id: str
+    finish_reason: str
+    tokens_used: int
+    latency_ms: float
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    metadata: dict[str, Any] = Field(default_factory=dict)

velune/core/types/memory.py

@@ -0,0 +1,42 @@
+"""Core memory type definitions."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryType(StrEnum):
+    """Types of memory records."""
+
+    WORKING = "working"
+    EPISODIC = "episodic"
+    SEMANTIC = "semantic"
+    PROCEDURAL = "procedural"
+    GRAPH = "graph"
+
+
+class MemoryRecord(BaseModel):
+    """A memory record."""
+
+    id: str
+    memory_type: MemoryType
+    content: str
+    embedding: list[float] | None = None
+    importance: float = Field(ge=0.0, le=1.0)
+    access_count: int = 0
+    last_accessed: datetime
+    created_at: datetime
+    expires_at: datetime | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class MemoryQuery(BaseModel):
+    """Query for memory retrieval."""
+
+    query_text: str
+    memory_types: list[MemoryType] = Field(default_factory=list)
+    limit: int = Field(default=10, ge=1, le=100)
+    min_importance: float = Field(default=0.0, ge=0.0, le=1.0)
+    metadata_filter: dict[str, Any] = Field(default_factory=dict)

velune/core/types/model.py

@@ -0,0 +1,70 @@
+"""Core model type definitions."""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelCapability(StrEnum):
+    """Capability categories used by the model router and classifiers."""
+
+    CODE_GENERATION = "code_generation"
+    CODE_ANALYSIS = "code_analysis"
+    REASONING = "reasoning"
+    PLANNING = "planning"
+    TOOL_USE = "tool_use"
+    DEBUGGING = "debugging"
+    REFACTORING = "refactoring"
+    SUMMARIZATION = "summarization"
+    RETRIEVAL = "retrieval"
+    MULTILINGUAL = "multilingual"
+    EMBEDDING = "embedding"
+    LONG_CONTEXT = "long_context"
+
+
+class CapabilityLevel(IntEnum):
+    """Capability proficiency levels."""
+
+    NONE = 0
+    BASIC = 25
+    INTERMEDIATE = 50
+    ADVANCED = 75
+    EXPERT = 100
+
+
+class ModelCapabilityProfile(BaseModel):
+    """Capability profile for a model."""
+
+    coding: CapabilityLevel = CapabilityLevel.NONE
+    reasoning: CapabilityLevel = CapabilityLevel.NONE
+    planning: CapabilityLevel = CapabilityLevel.NONE
+    summarization: CapabilityLevel = CapabilityLevel.NONE
+    embedding: CapabilityLevel = CapabilityLevel.NONE
+    instruction_following: CapabilityLevel = CapabilityLevel.NONE
+    multimodal: CapabilityLevel = CapabilityLevel.NONE
+    tool_use: CapabilityLevel = CapabilityLevel.NONE
+    long_context: CapabilityLevel = CapabilityLevel.NONE
+
+
+class ModelDescriptor(BaseModel):
+    """Descriptor for a model."""
+
+    model_config = ConfigDict(extra="allow")
+
+    model_id: str
+    provider_id: str
+    display_name: str
+    context_length: int
+    capabilities: Any
+    is_local: bool = False
+    quantization: str | None = None  # e.g. "Q4_K_M", "Q8_0"
+    vram_required_gb: float | None = None
+    parameter_count_b: float | None = None
+    speed_tier: Literal["fast", "medium", "slow"] = "medium"
+    cost_per_1k_tokens: float | None = None  # None for local models
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    family: str | None = None  # Model family for prompt adaptation (e.g., "qwen", "claude")

velune/core/types/provider.py

@@ -0,0 +1,62 @@
+"""Core provider type definitions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ProviderHealth(StrEnum):
+    """Provider health status."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNAVAILABLE = "unavailable"
+    UNKNOWN = "unknown"
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a provider."""
+
+    name: str
+    base_url: str
+    api_key: str | None = None
+    api_key_env: str | None = None
+    timeout: int = Field(default=30, ge=1)
+    max_retries: int = Field(default=3, ge=0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProviderCapabilities(BaseModel):
+    """Capabilities offered by a provider."""
+
+    supports_streaming: bool = False
+    supports_function_calling: bool = False
+    supports_embeddings: bool = False
+    max_context_window: int | None = None
+    rate_limit_rpm: int | None = None
+    rate_limit_tpm: int | None = None
+
+
+@dataclass
+class CapabilityManifest:
+    """Real-time capability and health manifest for a provider."""
+
+    provider_id: str
+    health: ProviderHealth
+    available_models: list[Any]
+    rate_limit_remaining: int | None = None
+    rate_limit_reset_at: float | None = None
+    estimated_latency_ms: int = 0
+    supports_streaming: bool = False
+    supports_tools: bool = False
+    is_online: bool = True
+    refreshed_at: float = field(default_factory=lambda: __import__("time").time())
+
+    @property
+    def is_available(self) -> bool:
+        """True if provider is not unavailable."""
+        return self.health != ProviderHealth.UNAVAILABLE

velune/core/types/repository.py

@@ -0,0 +1,38 @@
+"""Core repository type definitions."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FileNode(BaseModel):
+    """A file node in the repository."""
+
+    path: str
+    language: str | None = None
+    size_bytes: int
+    last_modified: float
+    is_ignored: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class SymbolNode(BaseModel):
+    """A symbol node (function, class, variable) in the repository."""
+
+    name: str
+    kind: str  # function, class, variable, etc.
+    file_path: str
+    line_start: int
+    line_end: int
+    parent: str | None = None
+    children: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class DependencyEdge(BaseModel):
+    """A dependency edge between nodes."""
+
+    source: str
+    target: str
+    edge_type: str  # import, call, inheritance, etc.
+    metadata: dict[str, Any] = Field(default_factory=dict)

velune/core/types/task.py

@@ -0,0 +1,61 @@
+"""Core task type definitions."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TaskStatus(StrEnum):
+    """Task execution status."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class Task(BaseModel):
+    """A task to be executed."""
+
+    id: str
+    description: str
+    status: TaskStatus = TaskStatus.PENDING
+    priority: int = Field(default=5, ge=1, le=10)
+    dependencies: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class TaskStep(BaseModel):
+    """A step within a task plan."""
+
+    id: str
+    description: str
+    agent_role: str
+    status: TaskStatus = TaskStatus.PENDING
+    dependencies: list[str] = Field(default_factory=list)
+    estimated_duration_ms: int | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class TaskPlan(BaseModel):
+    """A plan for executing a task."""
+
+    task_id: str
+    steps: list[TaskStep]
+    estimated_duration_ms: int | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class TaskResult(BaseModel):
+    """Result from task execution."""
+
+    task_id: str
+    success: bool
+    output: Any | None = None
+    error: str | None = None
+    steps_completed: int
+    steps_total: int
+    execution_time_ms: float
+    metadata: dict[str, Any] = Field(default_factory=dict)

velune/core/types/workspace.py

@@ -0,0 +1,28 @@
+"""Core workspace type definitions."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class WorkspaceState(StrEnum):
+    """Workspace state machine states."""
+
+    IDLE = "idle"
+    TASK_ACTIVE = "task_active"
+    DEBUGGING = "debugging"
+    REVIEWING = "reviewing"
+    INDEXING = "indexing"
+    ERROR = "error"
+
+
+class WorkspaceEvent(BaseModel):
+    """An event in the workspace."""
+
+    event_type: str
+    timestamp: datetime
+    source: str
+    data: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)

velune/daemon/client.py

@@ -0,0 +1,13 @@
+from velune.daemon.transport import IpcClient, get_ipc_address
+
+
+class DaemonClient:
+    """Thin client for communicating with Velune daemon."""
+
+    @staticmethod
+    def is_running() -> bool:
+        return IpcClient.is_running(get_ipc_address())
+
+    @staticmethod
+    async def send_command(command: str, **kwargs) -> dict:
+        return await IpcClient.send_command(get_ipc_address(), command, **kwargs)