velune-cli 0.9.0__py3-none-any.whl

velune/memory/vitality.py

@@ -0,0 +1,132 @@
+"""Vitality classification for memory retention and retrieval.
+
+Phase 2a: Recency-based vitality states (LIVE/ZOMBIE/ARCHIVED) determine
+whether a memory is eligible for inclusion in context retrieval.
+
+Classification is session-relative: a turn's vitality depends on how many
+sessions have passed since it was recorded.
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+import time
+from typing import Any
+
+logger = logging.getLogger("velune.memory.vitality")
+
+
+class Vitality(enum.Enum):
+    """Recency-based memory state for retrieval eligibility."""
+
+    LIVE = "live"  # Turn from last 3 sessions; always retrieved
+    ZOMBIE = "zombie"  # Turn from 4-10 sessions ago; retrieved only on LIVE miss
+    ARCHIVED = "archived"  # Turn > 10 sessions old; never retrieved (unless explicit)
+
+
+class VitalityClassifier:
+    """Classify memory vitality based on session distance and age."""
+
+    def __init__(
+        self,
+        live_window: int = 3,
+        zombie_window: int = 10,
+        ttl_seconds: float = 2_592_000,  # 30 days default
+    ) -> None:
+        """Initialize classifier with vitality thresholds.
+
+        Parameters
+        ----------
+        live_window:
+            Sessions from current: 0-N are LIVE (default 3 sessions).
+        zombie_window:
+            Sessions from current: (N+1)-M are ZOMBIE; >M are ARCHIVED (default 10).
+        ttl_seconds:
+            Max age in seconds before forced ARCHIVED (default 30 days).
+        """
+        self.live_window = live_window
+        self.zombie_window = zombie_window
+        self.ttl_seconds = ttl_seconds
+
+    def classify_turn(
+        self,
+        turn: Any,
+        current_session_index: int,
+        turn_session_index: int,
+        now: float | None = None,
+    ) -> Vitality:
+        """Classify a turn's vitality based on session distance and age.
+
+        Parameters
+        ----------
+        turn:
+            The turn object with a 'created_at' timestamp attribute.
+        current_session_index:
+            The ordinal index of the current session (0 = oldest).
+        turn_session_index:
+            The ordinal index of the session containing this turn.
+        now:
+            Current timestamp; defaults to time.time().
+
+        Returns
+        -------
+        Vitality:
+            One of LIVE, ZOMBIE, ARCHIVED.
+        """
+        if now is None:
+            now = time.time()
+
+        # Session distance: how many sessions old is this turn?
+        session_distance = current_session_index - turn_session_index
+
+        # Age-based cutoff: if turn is older than TTL, it's archived.
+        age = now - getattr(turn, "created_at", now)
+        if age > self.ttl_seconds:
+            return Vitality.ARCHIVED
+
+        # Session-based classification.
+        if session_distance <= self.live_window:
+            return Vitality.LIVE
+        if session_distance <= self.zombie_window:
+            return Vitality.ZOMBIE
+        return Vitality.ARCHIVED
+
+    def should_include(
+        self,
+        vitality: Vitality,
+        fallback_to_zombie: bool = False,
+    ) -> bool:
+        """Return True if a memory with this vitality should be retrieved.
+
+        Parameters
+        ----------
+        vitality:
+            The turn's vitality state.
+        fallback_to_zombie:
+            If True and no LIVE results found, include ZOMBIE (not default).
+
+        Returns
+        -------
+        bool:
+            True if the memory is eligible for retrieval.
+        """
+        if vitality == Vitality.LIVE:
+            return True
+        if fallback_to_zombie and vitality == Vitality.ZOMBIE:
+            return True
+        return False
+
+    def decay_factor(self, vitality: Vitality) -> float:
+        """Return a trust/confidence decay factor for this vitality.
+
+        LIVE memories have full confidence; ZOMBIE memories are discounted.
+        ARCHIVED memories should not appear, but if they do, score them low.
+        """
+        match vitality:
+            case Vitality.LIVE:
+                return 1.0
+            case Vitality.ZOMBIE:
+                return 0.6
+            case Vitality.ARCHIVED:
+                return 0.2

velune/models/__init__.py

@@ -0,0 +1,15 @@
+"""Model intelligence and capability layer."""
+
+from velune.models.profiler import ModelProfile, ModelProfiler
+from velune.models.registry import ModelCapabilityRegistry
+from velune.models.scorer import ModelScorer
+from velune.models.specializations import CouncilRole, ModelSpecializationMapper
+
+__all__ = [
+    "ModelCapabilityRegistry",
+    "ModelProfile",
+    "ModelProfiler",
+    "ModelScorer",
+    "CouncilRole",
+    "ModelSpecializationMapper",
+]

velune/models/family.py

@@ -0,0 +1,76 @@
+"""Model family detection and classification.
+
+Identifies model families by ID pattern to enable prompt format adaptation.
+Different families respond better to different prompt structures:
+- Qwen: ChatML format with <|im_start|>/<|im_end|>
+- DeepSeek: Specialized thinking prompt structure
+- Llama3: [INST] and <<SYS>> markers
+- Phi: Shorter, more direct prompts
+- Mistral: [INST] markers with different system placement
+- Gemma: Direct format similar to Llama
+- Cloud APIs: Standard message list format
+"""
+
+from __future__ import annotations
+
+import logging
+from enum import StrEnum
+
+logger = logging.getLogger("velune.models.family")
+
+
+class ModelFamily(StrEnum):
+    """Enumeration of model families with distinct prompt formats."""
+
+    QWEN = "qwen"
+    DEEPSEEK = "deepseek"
+    LLAMA3 = "llama3"
+    PHI = "phi"
+    MISTRAL = "mistral"
+    GEMMA = "gemma"
+    CLAUDE = "claude"
+    GPT = "gpt"
+    GEMINI = "gemini"
+    UNKNOWN = "unknown"
+
+
+def detect_family(model_id: str) -> ModelFamily:
+    """Detect model family from model ID string (case-insensitive).
+
+    Parameters
+    ----------
+    model_id:
+        The model identifier, e.g., "qwen:7b", "Claude-3", "deepseek-r1"
+
+    Returns
+    -------
+    ModelFamily:
+        The detected family, or UNKNOWN if no match.
+    """
+    if not model_id:
+        return ModelFamily.UNKNOWN
+
+    model_id_lower = model_id.lower()
+
+    # Check for exact or prefix matches (order matters for specificity)
+    if "qwen" in model_id_lower:
+        return ModelFamily.QWEN
+    if "deepseek" in model_id_lower or "deepseek-r1" in model_id_lower:
+        return ModelFamily.DEEPSEEK
+    if "llama" in model_id_lower:
+        return ModelFamily.LLAMA3
+    if "phi" in model_id_lower:
+        return ModelFamily.PHI
+    if "mistral" in model_id_lower:
+        return ModelFamily.MISTRAL
+    if "gemma" in model_id_lower:
+        return ModelFamily.GEMMA
+    if "claude" in model_id_lower:
+        return ModelFamily.CLAUDE
+    if "gpt" in model_id_lower or "gpt-4" in model_id_lower or "gpt-3.5" in model_id_lower:
+        return ModelFamily.GPT
+    if "gemini" in model_id_lower:
+        return ModelFamily.GEMINI
+
+    logger.debug("Unknown model family for model_id: %s", model_id)
+    return ModelFamily.UNKNOWN

velune/models/module.py

@@ -0,0 +1,20 @@
+from velune.kernel.bootstrap import RuntimeEnvironment, SubsystemModule
+
+
+def _create_model_registry(env: RuntimeEnvironment):
+    from velune.models.registry import ModelCapabilityRegistry
+
+    registry = ModelCapabilityRegistry()
+    # Register the scanner property for backward compatibility
+    env.container.register_instance("runtime.model_discovery", registry.scanner)
+    return registry
+
+
+MODEL_MODULES = [
+    SubsystemModule(
+        name="model_registry",
+        factory=_create_model_registry,
+        container_key="runtime.model_registry",
+        lifecycle_key="models",
+    )
+]

velune/models/probes.py

@@ -0,0 +1,192 @@
+"""Empirical capability probes and model prober engine."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ProbeResult:
+    capability: str
+    score: float  # 0.0 to 1.0
+    latency_ms: float
+    passed: bool
+    details: str = ""
+
+
+CODING_PROBE = """Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes. Return only the function, no explanation."""
+
+REASONING_PROBE = """If all bloops are razzles, and all razzles are lazzles, are all bloops lazzles? Answer with just Yes or No, then one sentence explanation."""
+
+INSTRUCTION_PROBE = (
+    """Respond with ONLY the JSON object {"status": "ok", "count": 42}. Nothing else."""
+)
+
+
+def _score_coding_response(response: str) -> float:
+    """Score coding probe response (0.0 to 1.0)."""
+    score = 0.0
+    if "def " in response:
+        score += 0.3
+    if "range(" in response:
+        score += 0.2
+    if "sieve" in response.lower() or ("for" in response and "%" in response):
+        score += 0.3
+    if "return" in response:
+        score += 0.2
+    return min(1.0, score)
+
+
+def _score_reasoning_response(response: str) -> float:
+    """Score reasoning probe response (0.0 to 1.0)."""
+    cleaned = response.strip().lower()
+    if not cleaned:
+        return 0.0
+
+    score = 0.0
+    if "yes" in cleaned:
+        score += 0.7
+        if len(cleaned) > 10:
+            score += 0.3
+    return min(1.0, score)
+
+
+def _score_instruction_response(response: str) -> float:
+    """Score instruction following probe response (0.0 to 1.0)."""
+    cleaned = response.strip()
+    # Clean possible markdown block wrappers
+    for prefix in ("```json", "```"):
+        if cleaned.startswith(prefix):
+            cleaned = cleaned[len(prefix) :]
+    if cleaned.endswith("```"):
+        cleaned = cleaned[:-3]
+    cleaned = cleaned.strip()
+
+    try:
+        import json
+
+        data = json.loads(cleaned)
+        if isinstance(data, dict):
+            if data.get("status") == "ok" and data.get("count") == 42:
+                return 1.0
+            return 0.5
+    except Exception:
+        pass
+    return 0.0
+
+
+class ModelProber:
+    """Runs lightweight capability probes against a specific model via its provider."""
+
+    def __init__(self, provider: Any, model_id: str) -> None:
+        self.provider = provider
+        self.model_id = model_id
+
+    async def run_coding_probe(self) -> ProbeResult:
+        """Run the coding capability probe."""
+        from velune.core.types.inference import InferenceRequest
+
+        start = time.perf_counter()
+        if not self.provider:
+            return ProbeResult("coding", 0.0, -1.0, False, "Provider not available")
+
+        try:
+            req = InferenceRequest(
+                model_id=self.model_id,
+                messages=[{"role": "user", "content": CODING_PROBE}],
+                temperature=0.1,
+                max_tokens=200,
+            )
+            response = await self.provider.infer(req)
+            latency_ms = (time.perf_counter() - start) * 1000.0
+            score = _score_coding_response(response.content)
+            return ProbeResult("coding", score, latency_ms, score > 0.5, response.content[:100])
+        except Exception as e:
+            return ProbeResult("coding", 0.0, -1.0, False, str(e))
+
+    async def run_reasoning_probe(self) -> ProbeResult:
+        """Run the deductive reasoning capability probe."""
+        from velune.core.types.inference import InferenceRequest
+
+        start = time.perf_counter()
+        if not self.provider:
+            return ProbeResult("reasoning", 0.0, -1.0, False, "Provider not available")
+
+        try:
+            req = InferenceRequest(
+                model_id=self.model_id,
+                messages=[{"role": "user", "content": REASONING_PROBE}],
+                temperature=0.1,
+                max_tokens=100,
+            )
+            response = await self.provider.infer(req)
+            latency_ms = (time.perf_counter() - start) * 1000.0
+            score = _score_reasoning_response(response.content)
+            return ProbeResult("reasoning", score, latency_ms, score > 0.5, response.content[:100])
+        except Exception as e:
+            return ProbeResult("reasoning", 0.0, -1.0, False, str(e))
+
+    async def run_instruction_probe(self) -> ProbeResult:
+        """Run the strict JSON instruction following capability probe."""
+        from velune.core.types.inference import InferenceRequest
+
+        start = time.perf_counter()
+        if not self.provider:
+            return ProbeResult("instruction", 0.0, -1.0, False, "Provider not available")
+
+        try:
+            req = InferenceRequest(
+                model_id=self.model_id,
+                messages=[{"role": "user", "content": INSTRUCTION_PROBE}],
+                temperature=0.1,
+                max_tokens=100,
+            )
+            response = await self.provider.infer(req)
+            latency_ms = (time.perf_counter() - start) * 1000.0
+            score = _score_instruction_response(response.content)
+            return ProbeResult(
+                "instruction", score, latency_ms, score > 0.5, response.content[:100]
+            )
+        except Exception as e:
+            return ProbeResult("instruction", 0.0, -1.0, False, str(e))
+
+    async def run_all_probes(self) -> dict[str, ProbeResult]:
+        """Run all capability probes in parallel."""
+        import asyncio
+
+        coding, reasoning, instruction = await asyncio.gather(
+            self.run_coding_probe(),
+            self.run_reasoning_probe(),
+            self.run_instruction_probe(),
+        )
+        return {"coding": coding, "reasoning": reasoning, "instruction": instruction}
+
+
+class FastProbe:
+    """Single lightweight probe to validate a model is responding."""
+
+    PING_PROMPT = "Reply with exactly the word: PONG"
+    TIMEOUT = 10.0
+
+    async def ping(self, provider: Any, model_id: str) -> bool:
+        """Returns True if model responds within timeout."""
+        import asyncio
+
+        from velune.core.types.inference import InferenceRequest
+
+        try:
+            req = InferenceRequest(
+                model_id=model_id,
+                messages=[{"role": "user", "content": self.PING_PROMPT}],
+                temperature=0.0,
+                max_tokens=5,
+            )
+            response = await asyncio.wait_for(
+                provider.infer(req),
+                timeout=self.TIMEOUT,
+            )
+            return bool(response.content.strip())
+        except Exception:
+            return False

velune/models/profile_cache.py

@@ -0,0 +1,84 @@
+"""Model profile caching layer for empirical benchmark results."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+
+class ModelProfileCache:
+    """Persists probe results to avoid re-probing on every invocation."""
+
+    CACHE_TTL_HOURS = 168  # Re-probe weekly (7 days * 24 hours = 168 hours)
+
+    def __init__(self, cache_path: Path) -> None:
+        self.cache_path = cache_path
+        self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def get(self, model_id: str, provider_id: str) -> dict | None:
+        """Retrieve cached probe results if present and fresh."""
+        if not self.cache_path.exists():
+            return None
+        try:
+            data = json.loads(self.cache_path.read_text())
+            key = f"{provider_id}/{model_id}"
+            entry = data.get(key)
+            if not entry:
+                return None
+
+            age_hours = (time.time() - entry["probed_at"]) / 3600.0
+            if age_hours > self.CACHE_TTL_HOURS:
+                return None  # Stale
+            return entry
+        except Exception:
+            return None
+
+    def set(self, model_id: str, provider_id: str, probe_results: dict) -> None:
+        """Cache probe results locally, converting dataclass results to dictionaries."""
+        import dataclasses
+
+        data = {}
+        if self.cache_path.exists():
+            try:
+                data = json.loads(self.cache_path.read_text())
+            except Exception:
+                pass
+
+        serialized_probes = {}
+        for cap, result in probe_results.items():
+            if dataclasses.is_dataclass(result):
+                serialized_probes[cap] = dataclasses.asdict(result)
+            elif isinstance(result, dict):
+                serialized_probes[cap] = result
+            else:
+                # Fallback mapping
+                serialized_probes[cap] = {
+                    "capability": cap,
+                    "score": getattr(result, "score", 0.0),
+                    "latency_ms": getattr(result, "latency_ms", -1.0),
+                    "passed": getattr(result, "passed", False),
+                    "details": getattr(result, "details", ""),
+                }
+
+        key = f"{provider_id}/{model_id}"
+        data[key] = {
+            "probed_at": time.time(),
+            "probes": serialized_probes,
+        }
+        import os
+        import tempfile
+
+        # Atomically write to temp file, then rename/replace
+        temp_dir = self.cache_path.parent
+        with tempfile.NamedTemporaryFile(
+            "w", dir=temp_dir, delete=False, encoding="utf-8"
+        ) as temp_file:
+            json.dump(data, temp_file, indent=2)
+            temp_file_name = temp_file.name
+        try:
+            os.replace(temp_file_name, str(self.cache_path))
+        except Exception:
+            if os.path.exists(temp_file_name):
+                os.remove(temp_file_name)
+            raise

velune/models/profiler.py

@@ -0,0 +1,108 @@
+"""Model profiling and dynamic metrics analysis."""
+
+from __future__ import annotations
+
+import time
+
+from pydantic import BaseModel, Field
+
+from velune.core.types.model import CapabilityLevel, ModelDescriptor
+from velune.providers.base import ModelProvider
+from velune.providers.benchmarker import ModelBenchmarkMetrics, ProviderBenchmarker
+
+
+class ModelProfile(BaseModel):
+    """Profile representing capability, speed, and real-time execution statistics."""
+
+    model_id: str
+    provider_id: str
+    avg_latency_ms: float = 0.0
+    p95_latency_ms: float = 0.0
+    sample_count: int = 0
+    tps: float = 0.0  # Tokens per second
+    ttft_ms: float = 0.0  # Time to first token
+    json_validity: float = 1.0  # Percentage structured compliance
+    last_updated: float = Field(default_factory=time.time)
+
+
+class ModelProfiler:
+    """Measures accuracy, response speed, and structure-matching capabilities."""
+
+    def __init__(self) -> None:
+        self._profiles: dict[str, ModelProfile] = {}
+        self._latency_samples: dict[str, list[float]] = {}
+
+    def record_execution(self, provider_id: str, model_id: str, latency_ms: float) -> None:
+        """Record real-time execution latency to build statistical latency profiles."""
+        key = f"{provider_id}/{model_id}"
+        if key not in self._latency_samples:
+            self._latency_samples[key] = []
+
+        samples = self._latency_samples[key]
+        samples.append(latency_ms)
+
+        # Enforce rolling history bounds to prevent memory bloat
+        if len(samples) > 100:
+            samples.pop(0)
+
+        sorted_samples = sorted(samples)
+        n = len(sorted_samples)
+
+        avg_lat = sum(samples) / n
+        p95_lat = sorted_samples[int(n * 0.95)] if n > 0 else avg_lat
+
+        if key in self._profiles:
+            profile = self._profiles[key]
+            profile.avg_latency_ms = avg_lat
+            profile.p95_latency_ms = p95_lat
+            profile.sample_count = n
+            profile.last_updated = time.time()
+        else:
+            self._profiles[key] = ModelProfile(
+                model_id=model_id,
+                provider_id=provider_id,
+                avg_latency_ms=avg_lat,
+                p95_latency_ms=p95_lat,
+                sample_count=n,
+            )
+
+    async def profile_model(
+        self, provider: ModelProvider, descriptor: ModelDescriptor
+    ) -> ModelProfile:
+        """Actively benchmark an operational provider model for performance and structure."""
+        key = f"{descriptor.provider_id}/{descriptor.model_id}"
+
+        # Run benchmarks
+        benchmarker = ProviderBenchmarker(provider, descriptor.model_id)
+        metrics: ModelBenchmarkMetrics = await benchmarker.evaluate()
+
+        # Build or update the profile
+        profile = self._profiles.get(key)
+        if not profile:
+            profile = ModelProfile(
+                model_id=descriptor.model_id,
+                provider_id=descriptor.provider_id,
+            )
+            self._profiles[key] = profile
+
+        profile.tps = metrics.tps
+        profile.ttft_ms = metrics.ttft_ms
+        profile.json_validity = metrics.json_validity
+        profile.last_updated = time.time()
+
+        # Update capability profile levels based on empirical benchmark results
+        capabilities = getattr(descriptor, "capabilities", None)
+        if capabilities and hasattr(capabilities, "tool_use") and metrics.json_validity < 0.5:
+            # Degrade tool use if model repeatedly fails structure test
+            capabilities.tool_use = CapabilityLevel.NONE
+
+        return profile
+
+    def get_profile(self, provider_id: str, model_id: str) -> ModelProfile | None:
+        """Look up the recorded profile for a model."""
+        key = f"{provider_id}/{model_id}"
+        return self._profiles.get(key)
+
+    def list_profiles(self) -> list[ModelProfile]:
+        """Enumerate all active profiles."""
+        return list(self._profiles.values())