gitops-by-veera 1.0.0__py3-none-any.whl

gitops_by_veera/__init__.py

@@ -0,0 +1,12 @@
+"""gitops-by-veera — conversational autonomous Git and GitHub operations coordinator."""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+__author__ = "Veera"
+__license__ = "MIT"
+
+from gitops_by_veera.agent import GitOpsAgent
+from gitops_by_veera.exceptions import GitOpsError
+
+__all__ = ["GitOpsAgent", "GitOpsError", "__version__"]

gitops_by_veera/agent.py

@@ -0,0 +1,436 @@
+"""Central orchestration engine: LLM calling, model cascading, execution, and self-healing."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import requests
+from pydantic import ValidationError
+
+from gitops_by_veera.config import find_repo_root
+from gitops_by_veera.constants import (
+    DIRECT_EVAL_MAP,
+    DIRECT_EVAL_PATTERNS,
+    GITHUB_API_BASE,
+    GITHUB_RATE_LIMIT_REMAINING_HEADER,
+    GITHUB_RATE_LIMIT_RESET_HEADER,
+    GROQ_API_URL,
+    GROQ_CONNECT_TIMEOUT,
+    GROQ_MAX_RETRIES,
+    GROQ_READ_TIMEOUT,
+    GROQ_RETRY_STATUSES,
+    MODEL_CASCADE,
+    MODEL_TIER_3,
+    REMEDIATION_PROMPT,
+    SYSTEM_PROMPT,
+)
+from gitops_by_veera.exceptions import (
+    ExecutionError,
+    GitHubAPIError,
+    GitHubRateLimitError,
+    GroqAPIError,
+    GroqRateLimitError,
+    GroqTimeoutError,
+    ModelCascadeExhaustedError,
+    ParseError,
+    RemediationLimitError,
+)
+from gitops_by_veera.logger import get_logger
+from gitops_by_veera.models import (
+    CloudOperation,
+    ExecutionPlan,
+    LocalOperation,
+    OperationResult,
+    SessionMetrics,
+)
+from gitops_by_veera.validator import validate_plan
+
+logger = get_logger("gitops.agent")
+
+MAX_REMEDIATION_CYCLES = 2
+
+
+class GitOpsAgent:
+    """Orchestrates LLM planning, validation, execution, and remediation."""
+
+    def __init__(
+        self,
+        groq_api_key: str,
+        github_token: str,
+        repo_root: Optional[Path] = None,
+        debug: bool = False,
+    ) -> None:
+        self._groq_key = groq_api_key
+        self._github_token = github_token
+        self._repo_root = repo_root or find_repo_root() or Path.cwd()
+        self._debug = debug
+        self._prompt_cache: dict[str, ExecutionPlan] = {}
+        self.metrics = SessionMetrics()
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def build_plan(self, prompt: str) -> ExecutionPlan:
+        """Convert a natural-language prompt into a validated execution plan.
+
+        Uses the direct-evaluation bypass for trivial inspection commands.
+        Falls back to LLM cascade otherwise. Results are cached per prompt.
+        """
+        direct = self._try_direct_eval(prompt)
+        if direct is not None:
+            logger.debug("Direct evaluation bypassed LLM for prompt: %r", prompt)
+            return direct
+
+        if prompt in self._prompt_cache:
+            logger.debug("Cache hit for prompt: %r", prompt)
+            return self._prompt_cache[prompt]
+
+        plan = self._call_llm_cascade(prompt, SYSTEM_PROMPT)
+        self._prompt_cache[prompt] = plan
+        return plan
+
+    def validate(self, plan: ExecutionPlan) -> list[str]:
+        """Validate the plan and return warning messages for risky operations."""
+        return validate_plan(plan, self._repo_root)
+
+    def execute(self, plan: ExecutionPlan, dry_run: bool = False) -> list[OperationResult]:
+        """Execute all operations in the plan sequentially.
+
+        If dry_run is True, operations are validated but not executed.
+        Failures trigger the self-healing remediation loop.
+        """
+        start = time.time()
+        results: list[OperationResult] = []
+        remediation_cycles = 0
+
+        for idx, op in enumerate(plan.operations):
+            if dry_run:
+                logger.info("[DRY-RUN] Would execute operation %d: %s", idx, op.type)
+                continue
+
+            if isinstance(op, LocalOperation):
+                result = self._run_local(idx, op)
+            else:
+                result = self._run_cloud(idx, op)  # type: ignore[arg-type]
+
+            results.append(result)
+
+            if not result.success:
+                self.metrics.record_failure()
+                if remediation_cycles >= MAX_REMEDIATION_CYCLES:
+                    raise RemediationLimitError(
+                        f"Remediation limit ({MAX_REMEDIATION_CYCLES}) reached. "
+                        "Please resolve the issue manually."
+                    )
+                remediation_cycles += 1
+                return results  # caller handles remediation loop
+
+            self.metrics.record_success()
+
+        self.metrics.total_execution_duration_seconds = time.time() - start
+        return results
+
+    def remediate(self, failed_result: OperationResult) -> ExecutionPlan:
+        """Ask the Tier 3 model for a remediation plan for a failed operation."""
+        self.metrics.record_remediation()
+        safe_context = {
+            "operation_type": failed_result.operation_type,
+            "error_message": failed_result.error_message,
+            "returncode": failed_result.returncode,
+            "stderr": failed_result.stderr[:500],
+        }
+        prompt = (
+            f"The following operation failed:\n{json.dumps(safe_context, indent=2)}\n\n"
+            "Suggest a safe remediation plan."
+        )
+        return self._call_llm_cascade(prompt, REMEDIATION_PROMPT, prefer_tier3=True)
+
+    # ------------------------------------------------------------------
+    # Direct evaluation
+    # ------------------------------------------------------------------
+
+    def _try_direct_eval(self, prompt: str) -> Optional[ExecutionPlan]:
+        for pattern in DIRECT_EVAL_PATTERNS:
+            if pattern.match(prompt.strip()):
+                key = self._classify_direct(prompt)
+                args = DIRECT_EVAL_MAP.get(key, ["status"])
+                raw = {
+                    "operations": [
+                        {
+                            "type": "local",
+                            "binary": "git",
+                            "args": args,
+                            "risk_level": "safe",
+                            "reason": f"Direct evaluation of '{prompt.strip()}'.",
+                        }
+                    ]
+                }
+                return ExecutionPlan(**raw)
+        return None
+
+    @staticmethod
+    def _classify_direct(prompt: str) -> str:
+        p = prompt.strip().lower()
+        if "diff" in p:
+            return "diff"
+        if "log" in p or "history" in p:
+            return "log"
+        return "status"
+
+    # ------------------------------------------------------------------
+    # LLM cascade
+    # ------------------------------------------------------------------
+
+    def _call_llm_cascade(
+        self, prompt: str, system_prompt: str, prefer_tier3: bool = False
+    ) -> ExecutionPlan:
+        models = [MODEL_TIER_3] if prefer_tier3 else MODEL_CASCADE
+
+        last_error: Exception = ModelCascadeExhaustedError("No models available.")
+
+        for model in models:
+            try:
+                logger.debug("Trying model: %s", model)
+                self.metrics.record_llm_call(model)
+                raw_json = self._call_groq(model, prompt, system_prompt)
+                plan = self._parse_plan(raw_json)
+                return plan
+            except (ParseError, ValidationError) as exc:
+                logger.warning("Model %s produced invalid JSON. Cascading. %s", model, exc)
+                self.metrics.record_fallback()
+                last_error = exc
+            except (GroqRateLimitError, GroqTimeoutError, GroqAPIError) as exc:
+                logger.warning("Model %s failed: %s. Cascading.", model, exc)
+                self.metrics.record_fallback()
+                last_error = exc
+
+        raise ModelCascadeExhaustedError(
+            f"All model tiers exhausted. Last error: {last_error}"
+        ) from last_error
+
+    def _call_groq(self, model: str, prompt: str, system_prompt: str) -> dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._groq_key}",
+            "Content-Type": "application/json",
+        }
+        body = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            "response_format": {"type": "json_object"},
+            "temperature": 0.1,
+        }
+
+        backoff = 1.0
+        for attempt in range(GROQ_MAX_RETRIES):
+            try:
+                response = requests.post(
+                    GROQ_API_URL,
+                    headers=headers,
+                    json=body,
+                    timeout=(GROQ_CONNECT_TIMEOUT, GROQ_READ_TIMEOUT),
+                )
+            except requests.Timeout:
+                logger.warning(
+                    "Groq API timeout (attempt %d/%d). Retrying...", attempt + 1, GROQ_MAX_RETRIES
+                )
+                if attempt < GROQ_MAX_RETRIES - 1:
+                    time.sleep(backoff)
+                    backoff *= 2
+                    continue
+                raise GroqTimeoutError("Groq API timed out after all retries.")
+            except requests.RequestException as exc:
+                raise GroqAPIError(f"Groq network error: {exc}") from exc
+
+            if response.status_code == 200:
+                try:
+                    return response.json()["choices"][0]["message"]["content"]
+                except (KeyError, IndexError, json.JSONDecodeError) as exc:
+                    raise ParseError(f"Unexpected Groq response structure: {exc}") from exc
+
+            if response.status_code in GROQ_RETRY_STATUSES:
+                logger.warning(
+                    "Groq returned %d (attempt %d/%d). Retrying in %.0fs...",
+                    response.status_code,
+                    attempt + 1,
+                    GROQ_MAX_RETRIES,
+                    backoff,
+                )
+                if attempt < GROQ_MAX_RETRIES - 1:
+                    time.sleep(backoff)
+                    backoff *= 2
+                    continue
+                raise GroqRateLimitError(
+                    f"Groq rate limit persists after {GROQ_MAX_RETRIES} retries.",
+                    status_code=response.status_code,
+                )
+
+            raise GroqAPIError(
+                f"Groq API error {response.status_code}: {response.text[:200]}",
+                status_code=response.status_code,
+            )
+
+        raise GroqAPIError("Groq retry loop exited without a result.")  # pragma: no cover
+
+    def _parse_plan(self, raw: Any) -> ExecutionPlan:
+        if isinstance(raw, str):
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                raise ParseError(f"LLM returned non-JSON string: {exc}") from exc
+        elif isinstance(raw, dict):
+            data = raw
+        else:
+            raise ParseError(f"Unexpected LLM output type: {type(raw)}")
+
+        try:
+            return ExecutionPlan(**data)
+        except (ValidationError, TypeError) as exc:
+            raise ParseError(f"Pydantic validation failed: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Local execution
+    # ------------------------------------------------------------------
+
+    def _run_local(self, idx: int, op: LocalOperation) -> OperationResult:
+        cmd = [op.binary] + op.args
+        logger.info("Executing local operation %d: %s", idx, " ".join(cmd))
+        try:
+            proc = subprocess.run(
+                cmd,
+                cwd=str(self._repo_root),
+                capture_output=True,
+                text=True,
+                shell=False,
+                timeout=60,
+            )
+            success = proc.returncode == 0
+            if not success:
+                logger.warning(
+                    "Local operation %d failed (rc=%d): %s", idx, proc.returncode, proc.stderr[:300]
+                )
+            return OperationResult(
+                operation_index=idx,
+                operation_type="local",
+                success=success,
+                stdout=proc.stdout,
+                stderr=proc.stderr,
+                returncode=proc.returncode,
+                error_message=proc.stderr if not success else "",
+            )
+        except subprocess.TimeoutExpired:
+            return OperationResult(
+                operation_index=idx,
+                operation_type="local",
+                success=False,
+                error_message="Command timed out after 60 seconds.",
+                returncode=-1,
+            )
+        except FileNotFoundError as exc:
+            return OperationResult(
+                operation_index=idx,
+                operation_type="local",
+                success=False,
+                error_message=f"Executable not found: {exc}",
+                returncode=-1,
+            )
+
+    # ------------------------------------------------------------------
+    # Cloud execution
+    # ------------------------------------------------------------------
+
+    def _run_cloud(self, idx: int, op: CloudOperation) -> OperationResult:
+        url = f"{GITHUB_API_BASE}{op.endpoint}"
+        headers = {
+            "Authorization": f"Bearer {self._github_token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "Content-Type": "application/json",
+        }
+        logger.info("Executing cloud operation %d: %s %s", idx, op.method, op.endpoint)
+
+        backoff = 2.0
+        for attempt in range(3):
+            try:
+                response = requests.request(
+                    op.method,
+                    url,
+                    headers=headers,
+                    json=op.payload if op.payload else None,
+                    timeout=(10, 30),
+                )
+            except requests.Timeout:
+                return OperationResult(
+                    operation_index=idx,
+                    operation_type="cloud",
+                    success=False,
+                    error_message="GitHub API request timed out.",
+                    status_code=0,
+                )
+            except requests.RequestException as exc:
+                return OperationResult(
+                    operation_index=idx,
+                    operation_type="cloud",
+                    success=False,
+                    error_message=f"Network error: {exc}",
+                    status_code=0,
+                )
+
+            if response.status_code in (403, 429):
+                remaining = response.headers.get(GITHUB_RATE_LIMIT_REMAINING_HEADER)
+                reset = response.headers.get(GITHUB_RATE_LIMIT_RESET_HEADER)
+
+                if remaining == "0" and reset:
+                    wait = max(0, int(reset) - int(time.time())) + 1
+                    logger.warning("GitHub rate limit hit. Waiting %ds until reset.", wait)
+                    time.sleep(min(wait, 60))
+                else:
+                    logger.warning(
+                        "GitHub %d response (attempt %d/3). Retrying in %.0fs...",
+                        response.status_code,
+                        attempt + 1,
+                        backoff,
+                    )
+                    time.sleep(backoff)
+                    backoff *= 2
+                continue
+
+            success = response.status_code in (200, 201, 204)
+            body_text = ""
+            try:
+                body_text = json.dumps(response.json())
+            except Exception:
+                body_text = response.text[:500]
+
+            if not success:
+                logger.warning(
+                    "Cloud operation %d failed (%d): %s",
+                    idx,
+                    response.status_code,
+                    body_text[:300],
+                )
+
+            return OperationResult(
+                operation_index=idx,
+                operation_type="cloud",
+                success=success,
+                stdout=body_text if success else "",
+                stderr=body_text if not success else "",
+                status_code=response.status_code,
+                error_message=body_text if not success else "",
+            )
+
+        return OperationResult(
+            operation_index=idx,
+            operation_type="cloud",
+            success=False,
+            error_message="GitHub API rate limit persists after retries. Please try later.",
+            status_code=429,
+        )