moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/loop/state.py

@@ -0,0 +1,209 @@
+# Loop State Data Models
+"""Data models for the Ralph-style autonomous feedback loop controller.
+
+These dataclasses represent the core types used for tracking loop execution,
+diagnostic snapshots, AST issue snapshots, and feedback results.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from datetime import datetime
+from enum import Enum
+
+
+class LoopStatus(Enum):
+    """Status of a feedback loop execution.
+
+    Values represent the current state of a loop:
+    - RUNNING: Loop is actively executing
+    - COMPLETED: Loop finished successfully (promise fulfilled)
+    - CANCELLED: Loop was cancelled by user
+    - FAILED: Loop failed due to an error
+    - PAUSED: Loop is temporarily paused
+    """
+
+    RUNNING = "running"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+    PAUSED = "paused"
+
+
+@dataclass
+class DiagnosticSnapshot:
+    """A snapshot of LSP diagnostics at a point in time.
+
+    Captures the state of LSP diagnostics during a loop iteration,
+    including counts by severity and affected files.
+
+    Attributes:
+        timestamp: When the snapshot was taken.
+        error_count: Number of error-level diagnostics.
+        warning_count: Number of warning-level diagnostics.
+        info_count: Number of info-level diagnostics.
+        files_affected: List of file paths with diagnostics.
+    """
+
+    timestamp: datetime
+    error_count: int
+    warning_count: int
+    info_count: int
+    files_affected: list[str]
+
+    def total_issues(self) -> int:
+        """Calculate total number of issues across all severities.
+
+        Returns:
+            Sum of error, warning, and info counts.
+        """
+        return self.error_count + self.warning_count + self.info_count
+
+    def has_errors(self) -> bool:
+        """Check if there are any error-level diagnostics.
+
+        Returns:
+            True if error_count > 0, False otherwise.
+        """
+        return self.error_count > 0
+
+
+@dataclass
+class ASTIssueSnapshot:
+    """A snapshot of AST-grep issues at a point in time.
+
+    Captures the state of AST-grep analysis during a loop iteration,
+    including issue counts by severity and rule.
+
+    Attributes:
+        timestamp: When the snapshot was taken.
+        total_issues: Total number of AST issues found.
+        by_severity: Count of issues by severity level.
+        by_rule: Count of issues by rule ID.
+        files_affected: List of file paths with issues.
+    """
+
+    timestamp: datetime
+    total_issues: int
+    by_severity: dict[str, int]
+    by_rule: dict[str, int]
+    files_affected: list[str]
+
+    def has_critical_issues(self) -> bool:
+        """Check if there are any critical (error) issues.
+
+        Returns:
+            True if there are error-severity issues, False otherwise.
+        """
+        return self.by_severity.get("error", 0) > 0
+
+
+@dataclass
+class LoopState:
+    """State of a feedback loop execution.
+
+    Tracks the complete state of a feedback loop including iteration
+    count, status, and history of diagnostics and AST issues.
+
+    Attributes:
+        loop_id: Unique identifier for the loop.
+        promise: The completion condition (e.g., "Fix all LSP errors").
+        current_iteration: Current iteration number (1-based).
+        max_iterations: Maximum allowed iterations.
+        status: Current loop status.
+        created_at: When the loop was created.
+        updated_at: When the loop was last updated.
+        diagnostics_history: History of diagnostic snapshots.
+        ast_issues_history: History of AST issue snapshots.
+    """
+
+    loop_id: str
+    promise: str
+    current_iteration: int
+    max_iterations: int
+    status: LoopStatus
+    created_at: datetime
+    updated_at: datetime
+    diagnostics_history: list[DiagnosticSnapshot] = field(default_factory=list)
+    ast_issues_history: list[ASTIssueSnapshot] = field(default_factory=list)
+
+    def is_active(self) -> bool:
+        """Check if the loop is in an active state.
+
+        Active states are RUNNING and PAUSED. Completed, cancelled,
+        and failed loops are not active.
+
+        Returns:
+            True if the loop is active, False otherwise.
+        """
+        return self.status in (LoopStatus.RUNNING, LoopStatus.PAUSED)
+
+    def can_continue(self) -> bool:
+        """Check if the loop can continue to the next iteration.
+
+        A loop can continue if it is active and has not reached
+        the maximum iteration limit.
+
+        Returns:
+            True if the loop can continue, False otherwise.
+        """
+        return self.is_active() and self.current_iteration < self.max_iterations
+
+    def increment_iteration(self) -> LoopState:
+        """Create a new LoopState with incremented iteration count.
+
+        Returns a new LoopState instance with current_iteration + 1,
+        preserving immutability of the original state.
+
+        Returns:
+            New LoopState with incremented iteration.
+        """
+        return replace(self, current_iteration=self.current_iteration + 1)
+
+
+@dataclass
+class CompletionResult:
+    """Result of checking loop completion conditions.
+
+    Contains information about whether the loop's promise has been
+    fulfilled and progress towards completion.
+
+    Attributes:
+        is_complete: Whether the completion condition is met.
+        reason: Human-readable explanation of the result.
+        remaining_issues: Number of issues still remaining.
+        progress_percentage: Percentage of progress towards completion.
+    """
+
+    is_complete: bool
+    reason: str
+    remaining_issues: int
+    progress_percentage: float
+
+
+@dataclass
+class FeedbackResult:
+    """Result of executing a feedback loop iteration.
+
+    Contains the diagnostic and AST snapshots from the iteration,
+    along with formatted feedback text and priority issues.
+
+    Attributes:
+        lsp_diagnostics: Snapshot of LSP diagnostics.
+        ast_issues: Snapshot of AST-grep issues.
+        feedback_text: Formatted feedback text for Claude.
+        priority_issues: List of highest-priority issues to address.
+    """
+
+    lsp_diagnostics: DiagnosticSnapshot
+    ast_issues: ASTIssueSnapshot
+    feedback_text: str
+    priority_issues: list[str]
+
+    def has_issues(self) -> bool:
+        """Check if there are any issues (LSP or AST).
+
+        Returns:
+            True if there are any LSP diagnostics or AST issues.
+        """
+        return self.lsp_diagnostics.total_issues() > 0 or self.ast_issues.total_issues > 0

moai_adk/loop/storage.py

@@ -0,0 +1,220 @@
+# Loop Storage
+"""Persistent storage for loop state management.
+
+Provides file-based storage for LoopState objects, enabling persistence
+across sessions and recovery of loop execution state.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from moai_adk.loop.state import (
+    ASTIssueSnapshot,
+    DiagnosticSnapshot,
+    LoopState,
+    LoopStatus,
+)
+
+
+class LoopStorage:
+    """File-based storage for loop states.
+
+    Manages persistence of LoopState objects to JSON files, enabling
+    state recovery and history tracking across sessions.
+
+    Attributes:
+        storage_dir: Path to the storage directory.
+    """
+
+    def __init__(self, storage_dir: str = ".moai/loop"):
+        """Initialize the loop storage.
+
+        Creates the storage directory if it doesn't exist.
+
+        Args:
+            storage_dir: Path to the storage directory.
+        """
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def save_state(self, state: LoopState) -> None:
+        """Save a loop state to storage.
+
+        Serializes the LoopState to JSON and writes it to a file
+        named after the loop_id.
+
+        Args:
+            state: The LoopState to save.
+        """
+        state_file = self.storage_dir / f"{state.loop_id}.json"
+        data = self._serialize_state(state)
+        with open(state_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, default=str)
+
+    def load_state(self, loop_id: str) -> LoopState | None:
+        """Load a loop state from storage.
+
+        Reads and deserializes a LoopState from the JSON file
+        corresponding to the loop_id.
+
+        Args:
+            loop_id: The ID of the loop to load.
+
+        Returns:
+            The loaded LoopState, or None if not found.
+        """
+        state_file = self.storage_dir / f"{loop_id}.json"
+        if not state_file.exists():
+            return None
+
+        with open(state_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        return self._deserialize_state(data)
+
+    def get_active_loop_id(self) -> str | None:
+        """Get the ID of the currently active loop.
+
+        Scans all stored loops and returns the ID of the most recently
+        updated loop that is in an active state (RUNNING or PAUSED).
+
+        Returns:
+            The loop_id of the active loop, or None if no active loop.
+        """
+        active_loops: list[tuple[str, datetime]] = []
+
+        for loop_id in self.list_loops():
+            state = self.load_state(loop_id)
+            if state is not None and state.is_active():
+                active_loops.append((loop_id, state.updated_at))
+
+        if not active_loops:
+            return None
+
+        # Return the most recently updated active loop
+        active_loops.sort(key=lambda x: x[1], reverse=True)
+        return active_loops[0][0]
+
+    def list_loops(self) -> list[str]:
+        """List all stored loop IDs.
+
+        Scans the storage directory for loop state files and
+        returns their IDs.
+
+        Returns:
+            List of loop IDs.
+        """
+        loop_ids = []
+        for file_path in self.storage_dir.glob("*.json"):
+            loop_ids.append(file_path.stem)
+        return loop_ids
+
+    def delete_state(self, loop_id: str) -> bool:
+        """Delete a loop state from storage.
+
+        Removes the JSON file corresponding to the loop_id.
+
+        Args:
+            loop_id: The ID of the loop to delete.
+
+        Returns:
+            True if the state was deleted, False if it didn't exist.
+        """
+        state_file = self.storage_dir / f"{loop_id}.json"
+        if not state_file.exists():
+            return False
+
+        state_file.unlink()
+        return True
+
+    def _serialize_state(self, state: LoopState) -> dict[str, Any]:
+        """Serialize a LoopState to a dictionary.
+
+        Converts the LoopState and its nested objects to a JSON-serializable
+        dictionary format.
+
+        Args:
+            state: The LoopState to serialize.
+
+        Returns:
+            Dictionary representation of the state.
+        """
+        return {
+            "loop_id": state.loop_id,
+            "promise": state.promise,
+            "current_iteration": state.current_iteration,
+            "max_iterations": state.max_iterations,
+            "status": state.status.value,
+            "created_at": state.created_at.isoformat(),
+            "updated_at": state.updated_at.isoformat(),
+            "diagnostics_history": [self._serialize_diagnostic_snapshot(s) for s in state.diagnostics_history],
+            "ast_issues_history": [self._serialize_ast_snapshot(s) for s in state.ast_issues_history],
+        }
+
+    def _serialize_diagnostic_snapshot(self, snapshot: DiagnosticSnapshot) -> dict[str, Any]:
+        """Serialize a DiagnosticSnapshot to a dictionary."""
+        return {
+            "timestamp": snapshot.timestamp.isoformat(),
+            "error_count": snapshot.error_count,
+            "warning_count": snapshot.warning_count,
+            "info_count": snapshot.info_count,
+            "files_affected": snapshot.files_affected,
+        }
+
+    def _serialize_ast_snapshot(self, snapshot: ASTIssueSnapshot) -> dict[str, Any]:
+        """Serialize an ASTIssueSnapshot to a dictionary."""
+        return {
+            "timestamp": snapshot.timestamp.isoformat(),
+            "total_issues": snapshot.total_issues,
+            "by_severity": snapshot.by_severity,
+            "by_rule": snapshot.by_rule,
+            "files_affected": snapshot.files_affected,
+        }
+
+    def _deserialize_state(self, data: dict[str, Any]) -> LoopState:
+        """Deserialize a dictionary to a LoopState.
+
+        Converts a JSON-deserialized dictionary back to a LoopState
+        with proper typing.
+
+        Args:
+            data: Dictionary representation of the state.
+
+        Returns:
+            The deserialized LoopState.
+        """
+        return LoopState(
+            loop_id=data["loop_id"],
+            promise=data["promise"],
+            current_iteration=data["current_iteration"],
+            max_iterations=data["max_iterations"],
+            status=LoopStatus(data["status"]),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            updated_at=datetime.fromisoformat(data["updated_at"]),
+            diagnostics_history=[self._deserialize_diagnostic_snapshot(s) for s in data.get("diagnostics_history", [])],
+            ast_issues_history=[self._deserialize_ast_snapshot(s) for s in data.get("ast_issues_history", [])],
+        )
+
+    def _deserialize_diagnostic_snapshot(self, data: dict[str, Any]) -> DiagnosticSnapshot:
+        """Deserialize a dictionary to a DiagnosticSnapshot."""
+        return DiagnosticSnapshot(
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            error_count=data["error_count"],
+            warning_count=data["warning_count"],
+            info_count=data["info_count"],
+            files_affected=data["files_affected"],
+        )
+
+    def _deserialize_ast_snapshot(self, data: dict[str, Any]) -> ASTIssueSnapshot:
+        """Deserialize a dictionary to an ASTIssueSnapshot."""
+        return ASTIssueSnapshot(
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            total_issues=data["total_issues"],
+            by_severity=data["by_severity"],
+            by_rule=data["by_rule"],
+            files_affected=data["files_affected"],
+        )

moai_adk/lsp/__init__.py

@@ -0,0 +1,70 @@
+# LSP Module
+"""MoAI-ADK LSP (Language Server Protocol) client implementation.
+
+This module provides:
+- LSP data models (Position, Range, Diagnostic, etc.)
+- JSON-RPC 2.0 protocol implementation
+- LSP server lifecycle management
+- LSP client interface for diagnostics, references, and more
+"""
+
+from moai_adk.lsp.client import LSPClientError, MoAILSPClient
+from moai_adk.lsp.models import (
+    Diagnostic,
+    DiagnosticSeverity,
+    HoverInfo,
+    Location,
+    Position,
+    Range,
+    TextDocumentIdentifier,
+    TextDocumentPositionParams,
+    TextEdit,
+    WorkspaceEdit,
+)
+from moai_adk.lsp.protocol import (
+    ContentLengthError,
+    JsonRpcError,
+    JsonRpcNotification,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    LSPProtocol,
+    ProtocolError,
+)
+from moai_adk.lsp.server_manager import (
+    LSPServer,
+    LSPServerConfig,
+    LSPServerManager,
+    ServerNotFoundError,
+    ServerStartError,
+)
+
+__all__ = [
+    # Client
+    "MoAILSPClient",
+    "LSPClientError",
+    # Models
+    "Position",
+    "Range",
+    "Location",
+    "DiagnosticSeverity",
+    "Diagnostic",
+    "TextDocumentIdentifier",
+    "TextDocumentPositionParams",
+    "TextEdit",
+    "WorkspaceEdit",
+    "HoverInfo",
+    # Protocol
+    "LSPProtocol",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "JsonRpcNotification",
+    "JsonRpcError",
+    "ProtocolError",
+    "ContentLengthError",
+    # Server Manager
+    "LSPServerManager",
+    "LSPServer",
+    "LSPServerConfig",
+    "ServerNotFoundError",
+    "ServerStartError",
+]