velm 0.1.2__py3-none-any.whl

velm/artisans/distill/core/inquisitor/temporal.py

@@ -0,0 +1,105 @@
+# scaffold/artisans/distill/core/inquisitor/temporal.py
+
+import subprocess
+import re
+from pathlib import Path
+from typing import Optional, Dict, Any
+from pydantic import BaseModel
+
+from .....logger import Scribe
+from .....contracts.heresy_contracts import ArtisanHeresy
+
+Logger = Scribe("TemporalInquisitor")
+
+
+class RegressionDossier(BaseModel):
+    commit_hash: str
+    author: str
+    date: str
+    message: str
+    affected_files: list[str]
+    diff: str
+
+
+class TemporalInquisitor:
+    """
+    =============================================================================
+    == THE TEMPORAL INQUISITOR (V-Ω-GIT-BISECT-AUTOMATOR)                      ==
+    =============================================================================
+    LIF: 10,000,000,000
+
+    Automates the 'git bisect' rite to pinpoint the exact moment a heresy
+    entered the timeline.
+    """
+
+    def __init__(self, project_root: Path):
+        self.root = project_root
+
+    def hunt(self, test_command: str, good_ref: str, bad_ref: str = "HEAD") -> Optional[RegressionDossier]:
+        """
+        Conducts the Bisect Rite.
+        """
+        Logger.info(f"Initiating Temporal Hunt between '{good_ref}' (Good) and '{bad_ref}' (Bad)...")
+
+        try:
+            # 1. Start Bisect
+            self._git(["bisect", "start"])
+            self._git(["bisect", "bad", bad_ref])
+            self._git(["bisect", "good", good_ref])
+
+            # 2. Run Automation
+            # We use 'git bisect run' with the provided shell command
+            Logger.info(f"Running automated inquest: [yellow]{test_command}[/yellow]")
+
+            # git bisect run expects the command to return 0 for good, 1-127 for bad (except 125)
+            # We wrap the command to ensure robust exit codes if needed,
+            # but usually the user provided command works (e.g. pytest).
+
+            proc = subprocess.run(
+                ["git", "bisect", "run", "sh", "-c", test_command],
+                cwd=self.root,
+                capture_output=True,
+                text=True
+            )
+
+            # 3. Analyze Result
+            if "is the first bad commit" in proc.stdout:
+                match = re.search(r"([a-f0-9]+) is the first bad commit", proc.stdout)
+                if match:
+                    bad_commit = match.group(1)
+                    return self._forge_dossier(bad_commit)
+
+            Logger.warn("The Temporal Inquest was inconclusive.")
+            return None
+
+        except Exception as e:
+            Logger.error(f"Temporal Inquest failed: {e}")
+            return None
+        finally:
+            self._git(["bisect", "reset"])
+
+    def _git(self, args: list[str]) -> str:
+        res = subprocess.run(["git"] + args, cwd=self.root, capture_output=True, text=True, check=True)
+        return res.stdout.strip()
+
+    def _forge_dossier(self, commit_hash: str) -> RegressionDossier:
+        """Extracts the soul of the bad commit."""
+        Logger.success(f"Regression identified at: [red]{commit_hash[:7]}[/red]")
+
+        # Get Metadata
+        info = self._git(["show", "-s", "--format=%an|%ad|%s", commit_hash]).split("|")
+
+        # Get Changed Files
+        files = self._git(["show", "--name-only", "--format=", commit_hash]).splitlines()
+
+        # Get Diff
+        diff = self._git(["show", commit_hash])
+
+        return RegressionDossier(
+            commit_hash=commit_hash,
+            author=info[0],
+            date=info[1],
+            message=info[2],
+            affected_files=[f.strip() for f in files if f.strip()],
+            diff=diff
+        )

velm/artisans/distill/core/inquisitor/testing.py

@@ -0,0 +1,59 @@
+# Path: artisans/distill/core/inquisitor/testing.py
+# -------------------------------------------------
+
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .....inquisitor import get_treesitter_gnosis
+
+
+class TestInquisitor:
+    """
+    =================================================================================
+    == THE TEST INQUISITOR (THE BOND FORGER'S EYE)                                 ==
+    =================================================================================
+    This divine artisan possesses a singular, focused Gaze. It looks only upon test
+    scriptures. Within their soul, it perceives their import statements to find every
+    symbol they summon from the application's core (`src/`, `app/`, etc.).
+
+    For each bond it perceives, it returns a tuple of `(test_file, source_file)`,
+    providing the `GraphBuilder` with the Gnosis required to forge the unbreakable,
+    bidirectional bond between a test and its source.
+    =================================================================================
+    """
+
+    def __init__(self, project_root: Path, all_files_set: set[str], symbol_map: dict[str, str]):
+        self.root = project_root
+        self.all_files = all_files_set
+        self.symbol_map = symbol_map
+
+    def find_bonds(self, test_file_path: Path) -> List[Tuple[str, str]]:
+        """
+        Performs the Gaze upon a single test file and returns all perceived bonds.
+        """
+        bonds = []
+        try:
+            content = test_file_path.read_text(encoding='utf-8')
+            gnosis = get_treesitter_gnosis(test_file_path, content)
+
+            if "error" in gnosis or "dependencies" not in gnosis:
+                return []
+
+            imported_symbols = gnosis["dependencies"].get("imported_symbols", [])
+            test_path_str = str(test_file_path.relative_to(self.root)).replace('\\', '/')
+
+            for symbol in imported_symbols:
+                # Ask the symbol map where this symbol lives
+                source_file_str = self.symbol_map.get(symbol.split('.')[-1]) # Use simple name for lookup
+
+                if source_file_str and source_file_str in self.all_files:
+                    # We found a link from a test to a source file.
+                    # We must ensure we are not linking to another test file.
+                    if 'test' not in source_file_str and 'spec' not in source_file_str:
+                        bonds.append((test_path_str, source_file_str))
+
+        except Exception:
+            return []
+
+        # Return unique bonds
+        return list(set(bonds))

velm/artisans/distill/core/oracle/__init__.py

@@ -0,0 +1,18 @@
+# Path: scaffold/artisans/distill/core/oracle/__init__.py
+# -------------------------------------------------------
+
+"""
+=================================================================================
+== THE ORACLE SANCTUM (V-Ω-MODULAR-MIND)                                       ==
+=================================================================================
+This sanctum houses the fractured soul of the Distillation Oracle.
+It orchestrates the five stages of Gnostic Distillation:
+1. Perception (The Cortex Gaze)
+2. Divination (Intent & Seeds)
+3. Propagation (Tracing & Causality)
+4. Adjudication (Ranking & Budgeting)
+5. Inscription (Weaving & Scribing)
+"""
+from .engine import DistillationOracle
+
+__all__ = ["DistillationOracle"]

velm/artisans/distill/core/oracle/adjudicator.py

@@ -0,0 +1,113 @@
+# === [scaffold/artisans/distill/core/oracle/adjudicator.py] - SECTION 1 of 1: The Adjudicator of Value ===
+import time
+from typing import Any, List
+from .....logger import Scribe
+from .contracts import OracleContext
+from .....core.cortex.ranking.engine import SignificanceRanker
+from ..governance import BudgetGovernor
+from ..consts import DEFAULT_BUDGET
+
+Logger = Scribe("OracleAdjudicator")
+
+
+class OracleAdjudicator:
+    """
+    =================================================================================
+    == THE FACULTY OF JUDGMENT (V-Ω-GNOSTIC-TRIBUNAL-ULTIMA)                        ==
+    =================================================================================
+    LIF: 100,000,000,000,000,000
+
+    The Fourth Movement. The High Judge of the Oracle.
+    It presides over the Tribunal of Value, orchestrating the Ranker and the Governor.
+
+    ### THE ASCENSION OF THE BRIDGE:
+    It now correctly bridges the gap between Divination and Ranking. It takes the
+    **Resolved Seed Paths** from the Diviner and passes them as the **Focus** for the
+    Ranker, ensuring the God-Ray Boost is applied to the files found, not just the
+    keywords requested.
+    """
+
+    def __init__(self, silent: bool = False):
+        self.silent = silent
+
+    def adjudicate(self, context: OracleContext):
+        """
+        Conducts the Rite of Adjudication.
+        Populates `context.ranked_inventory` and `context.governance_plan`.
+        """
+        t0 = time.time()
+
+        # --- PHASE A: VALUATION (THE RANKER'S JUDGMENT) ---
+
+        # [FACULTY 1] The Law of Dynamic Personas
+        persona_intent = context.query_intent.get('type', 'balanced') if context.query_intent else 'balanced'
+        if not self.silent:
+            Logger.info(f"Adjudicator summons the Ranker with Persona: [magenta]{persona_intent}[/magenta]")
+
+        # [FACULTY 2 & 3] The Gnostic Triage of Value
+
+        # [THE FIX] The Bridge of Seeds
+        # The Ranker expects 'focus' to contain the strings to match against file paths.
+        # The Diviner has already resolved the abstract 'GnosticLogicWeaver' into concrete paths in 'seed_files'.
+        # We must pass these concrete paths as the focus targets to ensure the God-Ray Boost (+10000) strikes them.
+
+        # We combine raw keywords (for loose matching) and resolved paths (for exact matching)
+        combined_focus = list(context.seed_files) + (context.profile.focus_keywords or [])
+
+        ranking_context = {
+            "query": context.profile.feature or "",
+            "intent": persona_intent,
+            "seeds": list(context.seed_files),
+            "traced": list(context.traced_files),
+            "impact_scores": context.impact_scores,
+            "reasons": context.context_reasons,
+            "ignore": context.profile.ignore or [],
+            # [THE FIX] Inject resolved paths as focus
+            "focus": combined_focus
+        }
+
+        # The Ranker assigns a 0-100 score to every file in the inventory.
+        ranker = SignificanceRanker(context.profile, context.memory, intent=persona_intent)
+
+        context.ranked_inventory = ranker.rank(context.memory.inventory, ranking_context)
+
+        t1 = time.time()
+        context.record_stat('ranking_ms', (t1 - t0) * 1000)
+
+        # --- PHASE B: GOVERNANCE (THE TREASURER'S DECREE) ---
+
+        # [FACULTY 4] The Polyglot Budgeteer
+        context.budget_limit = self._parse_budget(context.profile.token_budget)
+        if not self.silent:
+            Logger.info(f"The Treasury is set. Budget: [yellow]{context.budget_limit:,}[/yellow] tokens.")
+
+        governor = BudgetGovernor(context.budget_limit)
+
+        # The Governor generates the Plan (Map of File -> Tier).
+        context.governance_plan = governor.adjudicate_and_plan(context.ranked_inventory)
+
+        t2 = time.time()
+        context.record_stat('governance_ms', (t2 - t1) * 1000)
+
+    def _parse_budget(self, budget: Any) -> int:
+        """Parses human-readable budget strings (e.g. '800k', '1m')."""
+        if isinstance(budget, int):
+            return budget
+        if not budget:
+            return DEFAULT_BUDGET
+
+        s = str(budget).lower().strip()
+        multiplier = 1
+
+        if s.endswith('k'):
+            multiplier = 1000
+            s = s[:-1]
+        elif s.endswith('m'):
+            multiplier = 1000000
+            s = s[:-1]
+
+        try:
+            return int(float(s) * multiplier)
+        except ValueError:
+            Logger.warn(f"Invalid budget format '{budget}'. Defaulting to {DEFAULT_BUDGET}.")
+            return DEFAULT_BUDGET

velm/artisans/distill/core/oracle/contracts.py

@@ -0,0 +1,66 @@
+# Path: artisans/distill/core/oracle/contracts.py
+# -----------------------------------------------
+
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Set, Any, Optional
+from pathlib import Path
+
+# --- THE DIVINE SUMMONS ---
+from .....core.cortex.contracts import CortexMemory, FileGnosis, DistillationProfile
+
+
+
+@dataclass
+class OracleContext:
+    """
+    =============================================================================
+    == THE VESSEL OF ACCUMULATED GNOSIS (V-Ω-STATE-CONTAINER-HEALED)           ==
+    =============================================================================
+    A mutable, flowing vessel that travels through the Oracle's pipeline.
+    It accumulates Perception, Divination, Propagation, and Adjudication data.
+
+    [HEALED]: Now carries the `active_symbols` attribute to satisfy the
+    ContentWeaver's contract.
+    """
+    # --- The Architect's Will ---
+    root: Path
+    profile: DistillationProfile
+
+    # --- Stage 1: Perception (The Cortex) ---
+    memory: Optional[CortexMemory] = None
+
+    # --- Stage 2: Divination (The Seeds) ---
+    query_intent: Dict[str, Any] = field(default_factory=dict)
+    seed_files: Set[str] = field(default_factory=set)
+    # A map of "Why is this file here?" (e.g., "Semantic Search", "Stack Trace")
+    context_reasons: Dict[str, List[str]] = field(default_factory=dict)
+
+    # --- Stage 3: Propagation (The Web) ---
+    # Files touched by dynamic tracing or causal expansion
+    traced_files: Set[str] = field(default_factory=set)
+    # Scores calculated by the Causal Engine (Impact/Ripple effect)
+    impact_scores: Dict[str, int] = field(default_factory=dict)
+    # Captured runtime values (variable states)
+    runtime_state: Any = None
+
+    # [THE FIX] The Set of Active Symbols (for Skeletonizer filtering)
+    # This allows the Oracle to pass specific symbol focuses down to the Weaver.
+    active_symbols: Optional[Set[str]] = None
+
+    # --- Stage 4: Adjudication (The Verdict) ---
+    ranked_inventory: List[FileGnosis] = field(default_factory=list)
+    # Map: Path -> RepresentationTier (e.g. 'full', 'skeleton')
+    governance_plan: Dict[Path, str] = field(default_factory=dict)
+    budget_limit: int = 0
+
+    # --- Telemetry (The Pulse) ---
+    stats: Dict[str, Any] = field(default_factory=dict)
+
+    def add_reason(self, path: str, reason: str):
+        """Inscribes a reason for a file's inclusion into the Gnostic Record."""
+        self.context_reasons.setdefault(path, []).append(reason)
+
+    def record_stat(self, key: str, value: Any):
+        """Updates the internal telemetry ledger."""
+        self.stats[key] = value

velm/artisans/distill/core/oracle/diviner.py

@@ -0,0 +1,222 @@
+# === [scaffold/artisans/distill/core/oracle/diviner.py] - SECTION 1 of 1: The Ascended Diviner ===
+import time
+from pathlib import Path
+from typing import Set, Dict, List, Optional, Any
+
+from .....logger import Scribe
+from .contracts import OracleContext
+from .....contracts.heresy_contracts import ArtisanHeresy
+
+Logger = Scribe("OracleDiviner")
+
+
+class OracleDiviner:
+    """
+    =================================================================================
+    == THE FACULTY OF DIVINATION (V-Ω-SYMBOLIC-RESOLVER-ULTIMA)                    ==
+    =================================================================================
+    LIF: 100,000,000,000,000 (THE SEER OF SEEDS)
+
+    The Second Movement of the Oracle.
+    It transmutes the Architect's vague Intent (Keywords, Natural Language, Errors)
+    into concrete, physical Seed Files that serve as the roots of the Distillation.
+
+    ### THE PANTHEON OF 12 ASCENDED FACULTIES:
+
+    1.  **The Symbolic Resolution (THE FIX):** Uses the Cortex's `symbol_multimap` to
+        map abstract symbols ("MyClass") to physical files ("src/my_class.py").
+    2.  **The JIT Awakening:** Lazily imports heavy semantic and forensic engines only
+        when required, preventing circular import heresies.
+    3.  **The Physical Gaze:** Checks if a focus keyword matches an exact file path
+        on disk before attempting symbolic lookup.
+    4.  **The Fuzzy Resonance:** If symbolic lookup fails, scans all known file paths
+        for substring matches (e.g., "auth" matches "src/auth/service.py").
+    5.  **The Semantic Seer:** If `profile.feature` is set, summons the `SemanticEngine`
+        (RAG/Vector) to find files conceptually related to the request.
+    6.  **The Forensic Detective:** If `profile.problem_context` is set, summons the
+        `ForensicInquisitor` to parse stack traces and indict guilty files.
+    7.  **The Contextual Scribe:** Annotates every seed file with the *reason* for its
+        selection ("Explicit Focus", "Symbol: User", "Semantic Hit").
+    8.  **The Deduplication Ward:** Ensures a file is not added multiple times for
+        different reasons, though all reasons are chronicled.
+    9.  **The Path Normalizer:** Forces all seed paths to be POSIX-style relative
+        strings, ensuring harmony with the Graph and Ranker.
+    10. **The Telemetric Pulse:** Records precise timing data for the divination rite.
+    11. **The Unbreakable Ward:** Gracefully handles missing memory or empty profiles.
+    12. **The Intent Analyst:** Uses the `IntentAnalyzer` to expand natural language
+        queries into broader search terms.
+    """
+
+    def __init__(self, root: Path, silent: bool = False):
+        self.root = root
+        self.silent = silent
+
+        # --- FACULTY 2: THE JIT AWAKENING (HEALED) ---
+        try:
+            # [FIX]: New Core Imports
+            from .....core.semantics.engine import SemanticEngine
+            from .....core.semantics.intent import IntentAnalyzer
+            self.semantics_cls = SemanticEngine
+            self.intent_cls = IntentAnalyzer
+        except ImportError as e:
+            if not self.silent: Logger.warn(f"Semantic faculty is dormant ({e}).")
+            self.semantics_cls = None
+            self.intent_cls = None
+
+        try:
+            from ..forensics.engine import ForensicInquisitor
+            self.forensics_cls = ForensicInquisitor
+        except ImportError:
+            if not self.silent: Logger.warn("Forensic faculty is dormant. Error log analysis is disabled.")
+            self.forensics_cls = None
+
+    def divine(self, context: OracleContext):
+        """
+        The Grand Rite of Divination.
+        Populates `context.seed_files` and `context.context_reasons`.
+        """
+        t0 = time.time()
+
+        # --- MOVEMENT I: THE STRUCTURAL GAZE (FOCUS) ---
+        self._divine_structural_seeds(context)
+
+        # --- MOVEMENT II: THE SEMANTIC GAZE (INTENT) ---
+        self._divine_semantic_seeds(context)
+
+        # --- MOVEMENT III: THE FORENSIC GAZE (PROBLEM) ---
+        self._divine_forensic_seeds(context)
+
+        duration = (time.time() - t0) * 1000
+        context.record_stat('divination_ms', duration)
+
+        if not self.silent and context.seed_files:
+            Logger.info(f"Divination complete. {len(context.seed_files)} seed(s) identified.")
+
+    def _divine_structural_seeds(self, context: OracleContext):
+        """
+        [FACULTY 1 & 3 & 4] The Symbolic and Physical Resolution.
+        Maps `profile.focus_keywords` to file paths.
+        """
+        profile = context.profile
+        if not profile.focus_keywords:
+            return
+
+        # We need the memory to look up symbols
+        memory = context.memory
+        if not memory:
+            # Fallback to simple path checking if memory is void
+            for keyword in profile.focus_keywords:
+                if (self.root / keyword).exists():
+                    self._add_seed(context, keyword, "Explicit Focus")
+            return
+
+        for keyword in profile.focus_keywords:
+            found = False
+
+            # 1. The Physical Gaze (Exact Path)
+            # We check if the keyword is a valid path relative to root
+            potential_path = self.root / keyword
+            if potential_path.exists():
+                norm_path = str(potential_path.relative_to(self.root)).replace('\\', '/')
+                self._add_seed(context, norm_path, "Explicit Focus")
+                found = True
+
+            # 2. The Symbolic Gaze (Symbol Resolution)
+            # We check if the keyword is a Class, Function, or Module name known to the Cortex.
+            if keyword in memory.symbol_multimap:
+                files = memory.symbol_multimap[keyword]
+                for f in files:
+                    self._add_seed(context, f, f"Symbol: {keyword}")
+                found = True
+
+            # 2b. The Qualified Symbolic Gaze (e.g. "my_module.MyClass")
+            # If exact match failed, try splitting by dot
+            if not found and '.' in keyword:
+                simple_name = keyword.split('.')[-1]
+                if simple_name in memory.symbol_multimap:
+                    files = memory.symbol_multimap[simple_name]
+                    for f in files:
+                        self._add_seed(context, f, f"Symbol: {keyword}")
+                    found = True
+
+            # 3. The Fuzzy Resonance (Path Substring)
+            # If it's not a specific file or symbol, maybe it's a directory or partial name.
+            if not found:
+                keyword_lower = keyword.lower()
+                for file_gnosis in memory.inventory:
+                    path_str = str(file_gnosis.path).replace('\\', '/')
+                    if keyword_lower in path_str.lower():
+                        self._add_seed(context, path_str, f"Path Resonance: {keyword}")
+                        found = True
+
+            if not found and not self.silent:
+                Logger.verbose(f"   -> The Oracle found no resonance for focus keyword: '{keyword}'")
+
+    def _divine_semantic_seeds(self, context: OracleContext):
+        """[FACULTY 5 & 12] Semantic Search."""
+        profile = context.profile
+        if not profile.feature or not self.semantics_cls or not context.memory:
+            return
+
+        if not self.silent: Logger.info("Consulting Semantic Memory for intent...")
+
+        engine = self.semantics_cls(self.root, silent=True)
+        # Note: SemanticEngine handles intent analysis internally now
+        semantic_hits = engine.search(
+            profile.feature,
+            context.memory,
+            limit=5,  # Top 5 relevant files
+            interactive=profile.interactive_mode
+        )
+
+        if semantic_hits:
+            if not self.silent: Logger.success(f"Semantic Resonance found {len(semantic_hits)} matches.")
+            for f in semantic_hits:
+                self._add_seed(context, f, "Semantic Resonance")
+
+    def _divine_forensic_seeds(self, context: OracleContext):
+        """[FACULTY 6] Forensic Analysis."""
+        profile = context.profile
+        if not profile.problem_context or not self.forensics_cls:
+            return
+
+        if not self.silent: Logger.info("Conducting Forensic Inquest on problem context...")
+
+        inquisitor = self.forensics_cls(silent=True)
+        temp_scores = {}
+        # The Inquisitor updates temp_scores in-place based on stack trace parsing
+        inquisitor.gaze(profile.problem_context, temp_scores)
+
+        forensic_hits = list(temp_scores.keys())
+        if forensic_hits:
+            if not self.silent: Logger.success(f"Forensics identified {len(forensic_hits)} implicated files.")
+            for path in forensic_hits:
+                self._add_seed(context, path, "Forensic Trace")
+
+    def _add_seed(self, context: OracleContext, path: str, reason: str):
+        """[FACULTY 7, 8, 9] Adds a seed with normalization and reasoning."""
+        # Normalize to POSIX
+        clean_path = path.replace('\\', '/')
+
+        # Verify existence in the current reality (if we have memory)
+        if context.memory:
+            # Check if this path exists in the inventory keys
+            # (Inventory keys are usually relative posix paths)
+            if clean_path not in context.memory.project_gnosis and not any(
+                    str(f.path).replace('\\', '/') == clean_path for f in context.memory.inventory):
+                # It might be a directory?
+                if (self.root / clean_path).is_dir():
+                    # If directory, expand to all files inside?
+                    # For V1, we leave directory expansion to the user or fuzzy match
+                    pass
+                else:
+                    # Logger.verbose(f"   -> Seed '{clean_path}' not found in Cortex Memory. Ignoring.")
+                    pass
+                    # We can still add it if it exists on disk but missed by scanner (e.g. ignored file)
+                    if (self.root / clean_path).exists():
+                        pass
+                    else:
+                        return
+
+        context.seed_files.add(clean_path)
+        context.add_reason(clean_path, reason)