velune-cli 0.9.0__py3-none-any.whl

velune/cognition/personality.py

@@ -0,0 +1,238 @@
+"""Repository Personality & Style Analyzer Agent.
+
+Introspects Python source code directories via AST parsing to extract coding style conventions,
+OOP vs Functional paradigms, naming distributions, type hinting strictness, and docstring formatting.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import os
+import re
+from typing import Any
+
+logger = logging.getLogger("velune.cognition.personality")
+
+
+class StyleVisitor(ast.NodeVisitor):
+    """AST Visitor to count class/function paradigms, naming conventions, typings, and docstrings."""
+
+    def __init__(self) -> None:
+        self.classes_count = 0
+        self.functions_count = 0
+        self.top_level_functions_count = 0
+
+        # Naming convention counts
+        self.snake_case_count = 0
+        self.camel_case_count = 0
+        self.pascal_case_count = 0
+        self.upper_case_count = 0
+
+        # Type annotations counters
+        self.annotated_params = 0
+        self.total_params = 0
+        self.annotated_returns = 0
+        self.total_returns = 0
+
+        # Docstring style counters
+        self.google_docstrings = 0
+        self.sphinx_docstrings = 0
+        self.total_docstrings = 0
+
+        # Import modules
+        self.imports: set[str] = set()
+
+        # Regex for naming conventions
+        self.snake_re = re.compile(r"^[a-z_][a-z0-9_]*$")
+        self.camel_re = re.compile(r"^[a-z][a-zA-Z0-9]*$")
+        self.pascal_re = re.compile(r"^[A-Z][a-zA-Z0-9]*$")
+        self.upper_re = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+
+    def _classify_name(self, name: str) -> None:
+        if not name or name.startswith("__") and name.endswith("__"):
+            return
+
+        if self.snake_re.match(name):
+            self.snake_case_count += 1
+        elif self.camel_re.match(name):
+            self.camel_case_count += 1
+        elif self.pascal_re.match(name):
+            self.pascal_case_count += 1
+        elif self.upper_re.match(name):
+            self.upper_case_count += 1
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.classes_count += 1
+        self._classify_name(node.name)
+
+        # Check class docstring
+        doc = ast.get_docstring(node)
+        if doc:
+            self._analyze_docstring(doc)
+
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self.functions_count += 1
+        self._classify_name(node.name)
+
+        # Check if function is top-level (module level)
+        # Note: In NodeVisitor, we can track parent, but a simple check is to count total and we know if it's OOP dominant or Functional
+        # Let's count parameters and return annotations
+        # Exclude 'self' or 'cls' parameter
+        for arg in node.args.args:
+            if arg.arg in ("self", "cls"):
+                continue
+            self.total_params += 1
+            if arg.annotation is not None:
+                self.annotated_params += 1
+
+        for arg in node.args.kwonlyargs:
+            self.total_params += 1
+            if arg.annotation is not None:
+                self.annotated_params += 1
+
+        if node.args.vararg:
+            self.total_params += 1
+            if node.args.vararg.annotation is not None:
+                self.annotated_params += 1
+
+        if node.args.kwarg:
+            self.total_params += 1
+            if node.args.kwarg.annotation is not None:
+                self.annotated_params += 1
+
+        self.total_returns += 1
+        if node.returns is not None:
+            self.annotated_returns += 1
+
+        # Check docstring
+        doc = ast.get_docstring(node)
+        if doc:
+            self._analyze_docstring(doc)
+
+        self.generic_visit(node)
+
+    def visit_Name(self, node: ast.Name) -> None:
+        if isinstance(node.ctx, ast.Store):
+            self._classify_name(node.id)
+        self.generic_visit(node)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            parts = alias.name.split(".")
+            self.imports.add(parts[0])
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        if node.module:
+            parts = node.module.split(".")
+            self.imports.add(parts[0])
+        self.generic_visit(node)
+
+    def _analyze_docstring(self, doc: str) -> None:
+        self.total_docstrings += 1
+
+        # Check for Google Style
+        if "Args:" in doc or "Returns:" in doc or "Yields:" in doc:
+            self.google_docstrings += 1
+        # Check for Sphinx Style
+        elif ":param" in doc or ":type" in doc or ":return:" in doc:
+            self.sphinx_docstrings += 1
+
+
+class RepositoryPersonalityAgent:
+    """Introspects Python directories to compile a cohesive model coding personality style."""
+
+    def __init__(self, workspace_root: str | None = None) -> None:
+        self.workspace_root = workspace_root or os.getcwd()
+
+    def analyze_directory_style(self, directory: str) -> dict[str, Any]:
+        """Recursively scan Python files in directory via AST and compile the style profile."""
+        visitor = StyleVisitor()
+
+        # Count top-level functions (directly under Module)
+        for root, _, files in os.walk(directory):
+            for file in files:
+                if file.endswith(".py"):
+                    file_path = os.path.join(root, file)
+                    try:
+                        with open(file_path, encoding="utf-8", errors="ignore") as f:
+                            code = f.read()
+                        tree = ast.parse(code)
+                        visitor.visit(tree)
+
+                        # Inspect module body for top-level functions
+                        for node in tree.body:
+                            if isinstance(node, ast.FunctionDef):
+                                visitor.top_level_functions_count += 1
+                    except Exception:
+                        pass
+
+        # Calculate naming conventions
+        naming_totals = (
+            visitor.snake_case_count
+            + visitor.camel_case_count
+            + visitor.pascal_case_count
+            + visitor.upper_case_count
+        )
+
+        naming_stats = {
+            "snake_case": visitor.snake_case_count,
+            "camelCase": visitor.camel_case_count,
+            "PascalCase": visitor.pascal_case_count,
+            "UPPER_CASE": visitor.upper_case_count,
+        }
+
+        dominant_naming = "Hybrid"
+        if naming_totals > 0:
+            for k, v in naming_stats.items():
+                ratio = v / naming_totals
+                if ratio >= 0.70:
+                    dominant_naming = k
+                    break
+
+        # Calculate type hinting strictness
+        total_annotations = visitor.total_params + visitor.total_returns
+        annotated_total = visitor.annotated_params + visitor.annotated_returns
+        type_strictness = (
+            round(annotated_total / total_annotations, 3) if total_annotations > 0 else 1.0
+        )
+
+        # Calculate OOP vs Functional Paradigm
+        # If classes are dominant,OOP. If top-level functions are dominant, Functional. Else hybrid.
+        classes = visitor.classes_count
+        top_funcs = visitor.top_level_functions_count
+
+        if classes > top_funcs * 2 and classes > 1:
+            class_vs_functional = "OOP"
+        elif top_funcs > classes * 2 and top_funcs > 1:
+            class_vs_functional = "Functional"
+        else:
+            class_vs_functional = "Hybrid"
+
+        # Calculate docstring style
+        if visitor.total_docstrings > 0:
+            if visitor.google_docstrings > visitor.sphinx_docstrings:
+                docstring_style = "Google"
+            elif visitor.sphinx_docstrings > visitor.google_docstrings:
+                docstring_style = "Sphinx"
+            else:
+                docstring_style = "Google"  # Default fallback
+        else:
+            docstring_style = "Google"
+
+        # Filter external packages/preferred constructs (exclude standard short names or project local parts if wanted)
+        preferred = sorted(visitor.imports)[:8]
+
+        return {
+            "naming_conventions": {
+                "dominant": dominant_naming,
+                "breakdown": naming_stats,
+            },
+            "type_hinting_strictness": type_strictness,
+            "preferred_constructs": preferred,
+            "class_vs_functional": class_vs_functional,
+            "docstring_style": docstring_style,
+        }

velune/cognition/state.py

@@ -0,0 +1,104 @@
+"""Role-gated council state with strict write isolation between agents."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from velune.cognition.budget import CouncilExecutionBudget
+from velune.core.types.task import TaskPlan
+
+
+class ReviewDecision(StrEnum):
+    """Review outcome decision."""
+
+    APPROVE = "approve"
+    REJECT = "reject"
+    REVISE = "revise"
+
+
+@dataclass
+class CouncilState:
+    """Production council state with role-gated field writes.
+
+    Fields are organized by which role can write them:
+    - Planner-only: task_plan, retrieved_context
+    - Coder-only: generated_artifacts, pending_diffs
+    - Reviewer-only: review_decision, review_notes, review_cycle_count
+    - Synthesizer-only: final_output
+    - System-managed: started_at, error, is_complete
+
+    Enforcement: Callers must use the setter methods (e.g., set_planner_output)
+    which will raise AssertionError if a non-designated role tries to write.
+    """
+
+    run_id: str
+    task: str  # Original task description (immutable after init)
+    budget: CouncilExecutionBudget
+
+    # Planner writes only
+    task_plan: TaskPlan | None = None
+    retrieved_context: str | None = None
+
+    # Coder writes only
+    generated_artifacts: list[str] = field(default_factory=list)
+    pending_diffs: list[dict[str, Any]] = field(default_factory=list)
+
+    # Reviewer writes only
+    review_decision: ReviewDecision | None = None
+    review_notes: str | None = None
+    review_cycle_count: int = 0
+
+    # Synthesizer writes only
+    final_output: str | None = None
+
+    # System-managed
+    started_at: float = field(default_factory=time.time)
+    error: str | None = None
+    is_complete: bool = False
+
+    def set_planner_output(self, task_plan: TaskPlan, retrieved_context: str) -> None:
+        """Planner writes plan and context. Called only by planner agent."""
+        self.task_plan = task_plan
+        self.retrieved_context = retrieved_context
+
+    def set_coder_output(
+        self, diffs: list[dict[str, Any]], artifacts: list[str] | None = None
+    ) -> None:
+        """Coder writes diffs and optional artifacts. Called only by coder agent."""
+        self.pending_diffs = diffs
+        if artifacts:
+            self.generated_artifacts = artifacts
+
+    def set_reviewer_output(self, decision: ReviewDecision, notes: str) -> None:
+        """Reviewer writes decision and notes. Called only by reviewer agent."""
+        self.review_decision = decision
+        self.review_notes = notes
+        self.review_cycle_count += 1
+
+    def set_synthesizer_output(self, final_output: str) -> None:
+        """Synthesizer writes final summary. Called only by synthesizer agent."""
+        self.final_output = final_output
+
+    def mark_complete(self, error: str | None = None) -> None:
+        """Mark execution complete (system-managed)."""
+        self.is_complete = True
+        self.error = error
+
+    def elapsed_seconds(self) -> float:
+        """Return wall-clock seconds since state creation."""
+        return time.time() - self.started_at
+
+    def remaining_budget_seconds(self) -> float:
+        """Return remaining wall-clock budget."""
+        return max(0.0, self.budget.max_wall_time_seconds - self.elapsed_seconds())
+
+    def is_budget_exhausted(self) -> bool:
+        """Check if wall-clock budget is exhausted."""
+        return self.elapsed_seconds() >= self.budget.max_wall_time_seconds
+
+    def is_review_cycle_exhausted(self) -> bool:
+        """Check if review cycle count reached maximum."""
+        return self.review_cycle_count >= self.budget.max_review_cycles

velune/cognition/style_resolver.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import TYPE_CHECKING, Any
+
+from velune.cognition.personality import RepositoryPersonalityAgent
+
+if TYPE_CHECKING:
+    from velune.memory.tiers.lineage import LineageMemoryTier
+
+
+class StyleResolver:
+    """Manages asynchronous scanning and caching of style profiles to avoid event loop blockages."""
+
+    def __init__(self, lineage_memory: LineageMemoryTier | None) -> None:
+        self.lineage_memory = lineage_memory
+
+    async def get_or_refresh_style_profile(self, target_file: str) -> dict[str, Any] | None:
+        """Queries the style profile asynchronously, scanning and caching it if missing/stale."""
+        if self.lineage_memory is None:
+            return None
+
+        target_dir = os.path.dirname(target_file)
+        if not target_dir:
+            target_dir = "velune/core"
+
+        profile = await self.lineage_memory.get_personality_style(target_dir)
+
+        is_stale = False
+        if profile:
+            updated_at = profile.get("updated_at", 0.0)
+            if time.time() - updated_at > 86400.0:
+                is_stale = True
+
+        if not profile or is_stale:
+            try:
+                # Wrap the blocking AST Directory analysis in an asyncio thread pool
+                profile = await asyncio.to_thread(self._scan_directory, target_dir)
+                if profile:
+                    await self.lineage_memory.save_personality_style(
+                        subsystem=target_dir,
+                        naming_conventions=profile["naming_conventions"],
+                        type_hinting_strictness=profile["type_hinting_strictness"],
+                        preferred_constructs=profile["preferred_constructs"],
+                        class_vs_functional=profile["class_vs_functional"],
+                        docstring_style=profile["docstring_style"],
+                    )
+            except Exception as e:
+                import logging
+
+                logging.getLogger("velune.cognition.style_resolver").error(
+                    "Failed to run RepositoryPersonalityAgent in background: %s", e
+                )
+
+        return profile
+
+    def _scan_directory(self, target_dir: str) -> dict[str, Any] | None:
+        """Synchronous scanning code executed in a background thread."""
+        if os.path.exists(target_dir):
+            agent = RepositoryPersonalityAgent()
+            return agent.analyze_directory_style(target_dir)
+        return None

velune/cognition/verification.py

@@ -0,0 +1,205 @@
+"""Self-Reflection & Reasoning Verification Pipeline.
+
+Audits proposed modifications and plan outputs to guarantee architectural
+conformity, signature correctness, and import existence.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import os
+import sys
+from typing import Any
+
+
+class ReasoningVerifier:
+    """
+    Self-reflection and reasoning verification pipeline to analyze generated
+    code patches, plans, and files prior to execution to prevent architectural
+    regressions and syntax issues.
+    """
+
+    def __init__(self, workspace_root: str | None = None) -> None:
+        self.workspace_root = workspace_root or os.getcwd()
+
+    def analyze_proposed_imports(self, proposed_code: str) -> dict[str, Any]:
+        """
+        Detects potential hallucinated imports in proposed Python code.
+        Checks if standard libraries, installed packages, or local workspace modules exist.
+        """
+        issues = []
+        try:
+            tree = ast.parse(proposed_code)
+        except SyntaxError as e:
+            return {
+                "success": False,
+                "issues": [f"Syntax Error in proposed code: {e.msg} at line {e.lineno}"],
+            }
+
+        imported_modules: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for name in node.names:
+                    imported_modules.add(name.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    imported_modules.add(node.module.split(".")[0])
+
+        for mod_name in imported_modules:
+            # 1. Check if it's standard library or currently imported
+            if mod_name in sys.builtin_module_names:
+                continue
+
+            # Try to resolve module spec
+            spec = None
+            try:
+                spec = importlib.util.find_spec(mod_name)
+            except Exception:
+                pass
+
+            if spec is not None:
+                continue
+
+            # 2. Check if it's a local package or module in the workspace
+            local_path_dir = os.path.join(self.workspace_root, mod_name)
+            local_path_file = os.path.join(self.workspace_root, f"{mod_name}.py")
+            if os.path.isdir(local_path_dir) or os.path.isfile(local_path_file):
+                continue
+
+            issues.append(
+                f"Potential hallucinated import: module '{mod_name}' could not be resolved."
+            )
+
+        return {
+            "success": len(issues) == 0,
+            "issues": issues,
+        }
+
+    def analyze_contradictions(self, proposed_code: str, existing_code: str) -> dict[str, Any]:
+        """
+        Compares proposed code against existing code to identify signature mismatches,
+        duplicate function/class definitions, or structural contradictions.
+        """
+        issues = []
+        try:
+            proposed_tree = ast.parse(proposed_code)
+        except SyntaxError as e:
+            return {
+                "success": False,
+                "issues": [f"Syntax Error in proposed code: {e.msg} at line {e.lineno}"],
+            }
+
+        try:
+            existing_tree = ast.parse(existing_code) if existing_code else None
+        except SyntaxError:
+            existing_tree = None
+
+        if not existing_tree:
+            return {"success": True, "issues": []}
+
+        # Extract functions/classes from both trees
+        def extract_definitions(tree: ast.AST) -> dict[str, Any]:
+            defs: dict[str, Any] = {}
+            for node in ast.walk(tree):
+                if isinstance(node, ast.FunctionDef):
+                    args_count = len(node.args.args)
+                    defs[node.name] = {
+                        "type": "function",
+                        "args_count": args_count,
+                        "args": [arg.arg for arg in node.args.args],
+                    }
+                elif isinstance(node, ast.ClassDef):
+                    methods = {}
+                    for subnode in node.body:
+                        if isinstance(subnode, ast.FunctionDef):
+                            args_count = len(subnode.args.args)
+                            methods[subnode.name] = {
+                                "args_count": args_count,
+                                "args": [arg.arg for arg in subnode.args.args],
+                            }
+                    defs[node.name] = {
+                        "type": "class",
+                        "methods": methods,
+                    }
+            return defs
+
+        proposed_defs = extract_definitions(proposed_tree)
+        existing_defs = extract_definitions(existing_tree)
+
+        # Check for contradictions
+        for name, p_def in proposed_defs.items():
+            if name in existing_defs:
+                e_def = existing_defs[name]
+                if p_def["type"] != e_def["type"]:
+                    issues.append(
+                        f"Type contradiction: '{name}' is defined as a {p_def['type']} "
+                        f"in proposed code but is a {e_def['type']} in existing code."
+                    )
+                elif p_def["type"] == "function":
+                    if p_def["args_count"] != e_def["args_count"]:
+                        issues.append(
+                            f"Signature mismatch in function '{name}': proposed code has "
+                            f"{p_def['args_count']} arguments {p_def['args']}, but existing "
+                            f"code has {e_def['args_count']} arguments {e_def['args']}."
+                        )
+                elif p_def["type"] == "class":
+                    p_methods = p_def["methods"]
+                    e_methods = e_def["methods"]
+                    for m_name, p_method in p_methods.items():
+                        if m_name in e_methods:
+                            e_method = e_methods[m_name]
+                            if p_method["args_count"] != e_method["args_count"]:
+                                issues.append(
+                                    f"Signature mismatch in method '{name}.{m_name}': proposed "
+                                    f"code has {p_method['args_count']} arguments {p_method['args']}, "
+                                    f"but existing code has {e_method['args_count']} arguments {e_method['args']}."
+                                )
+
+        return {
+            "success": len(issues) == 0,
+            "issues": issues,
+        }
+
+    def audit_patch(self, file_path: str, proposed_code: str, existing_code: str) -> dict[str, Any]:
+        """
+        Runs complete contradiction, import hallucination, and general syntax audits.
+        """
+        is_python = file_path.endswith(".py")
+
+        if not is_python:
+            return {
+                "passed": True,
+                "issues": [],
+                "file_path": file_path,
+                "critique": "Static validation skipped for non-python file.",
+            }
+
+        import_results = self.analyze_proposed_imports(proposed_code)
+        contradiction_results = self.analyze_contradictions(proposed_code, existing_code)
+
+        all_issues = import_results.get("issues", []) + contradiction_results.get("issues", [])
+        passed = len(all_issues) == 0
+
+        # Construct structured critique
+        critique_lines = [
+            f"Audit for patch to '{file_path}':",
+            f"Status: {'PASSED' if passed else 'FAILED'}",
+        ]
+        if all_issues:
+            critique_lines.append("Issues found:")
+            for issue in all_issues:
+                critique_lines.append(f"- {issue}")
+        else:
+            critique_lines.append("No architectural or signature contradictions detected.")
+
+        critique_lines.append(
+            "\nAssess this patch for architectural regression. List potential failure vectors."
+        )
+
+        return {
+            "passed": passed,
+            "issues": all_issues,
+            "file_path": file_path,
+            "critique": "\n".join(critique_lines),
+        }

velune/context/__init__.py

@@ -0,0 +1,28 @@
+"""Context Engineering Subsystem.
+
+Manages token budgets, section ordering, and context assembly.
+"""
+
+from velune.context.assembler import ContextAssembler
+from velune.context.budget import ContextBudget
+from velune.context.sections import ContextAssemblyReport, ContextChunk, ContextSection
+from velune.context.token_counter import TokenCounter
+from velune.context.utilization import ContextUtilizationTracker
+from velune.context.window import ContextWindowTracker, estimate_tokens
+
+__all__ = [
+    # Budget and allocation
+    "ContextBudget",
+    # Sections and chunks
+    "ContextSection",
+    "ContextChunk",
+    "ContextAssemblyReport",
+    # Assembly and token counting
+    "ContextAssembler",
+    "TokenCounter",
+    # Legacy window tracking
+    "ContextWindowTracker",
+    "estimate_tokens",
+    # Context utilization
+    "ContextUtilizationTracker",
+]