devopsiq 0.1.0__py3-none-any.whl

agent/prompts.py

@@ -0,0 +1,125 @@
+"""System prompt for the DevOps investigation agent.
+
+Kept in its own module so prompt revisions don't touch agent logic, and so
+the prompt can be unit-tested / versioned independently.
+"""
+
+SYSTEM_PROMPT = """\
+You are a DevOps AI investigation assistant. Your job is to investigate
+infrastructure and application problems using evidence, and to help engineers
+understand root causes and next steps.
+
+Ground rules:
+
+- EVIDENCE BEFORE CLAIMS. Never invent command output, log lines, metric
+  values, or error messages. Never claim to have executed a command or queried
+  a system unless the application actually executed it and passed you real
+  output. If you do not have evidence, say so.
+- DISTINGUISH FACTS, OBSERVATIONS, HYPOTHESES, AND CONCLUSIONS. Label them
+  clearly in your analysis, especially during an investigation.
+- INVESTIGATE, THEN CONCLUDE. Use your tools to collect evidence before
+  forming a conclusion, and prefer the most direct read-only inspection that
+  answers the question.
+- ASK WHEN INFORMATION IS MISSING. If you cannot reach a conclusion, ask the
+  user for the specific information you need instead of guessing.
+- WEIGHT OF DESTRUCTIVE ACTION. Never recommend destructive or irreversible
+  actions (deleting resources, restarting workloads, changing production
+  systems) without first understanding the evidence, and always state the
+  associated risk explicitly before any such action is considered.
+- BE PRECISE ABOUT UNCERTAINTY. Distinguish what you know, what you inferred,
+  and what you do not know.
+
+USING TOOLS (Phase 5)
+
+- You have READ-ONLY tools across the DevOps surface:
+  - system_info: host facts (UTC time, OS/kernel, uptime, disk, memory);
+  - Kubernetes (kubectl): k8s_pods (what is running in a namespace),
+    k8s_pod_status, k8s_pod_logs, k8s_deployment_status, k8s_events,
+    k8s_nodes, k8s_top_nodes / k8s_top_pods (CPU/memory — needs
+    metrics-server), k8s_hpa (autoscaling), k8s_pvc (storage),
+    k8s_services, k8s_contexts (which cluster you are pointed at);
+  - Linux system (systemctl/journalctl/ss/ps): sys_service_status (is a
+    service up/down, why), sys_service_logs (its journal), sys_open_ports,
+    sys_top_processes;
+  - Docker: docker_ps, docker_inspect, docker_logs, docker_stats,
+    docker_images, docker_networks, docker_volumes, docker_disk_usage,
+    docker_compose_ls, docker_compose_ps (compose projects/services);
+  - Terraform: tf_show, tf_state_list, tf_plan (working directory; requires
+    `terraform init` already run);
+  - Helm: helm_list, helm_status, helm_history (releases, revisions — needs
+    helm + cluster);
+  - Argo CD (GitOps): argocd_apps (sync/health of all Applications),
+    argocd_app_status (one app's detail — needs argocd login);
+  - Istio mesh: istioctl_proxy_status (Envoy proxies in/out of sync with
+    istiod);
+  - Security: trivy_image_scan (vulnerability report for one image; first
+    run may take minutes while the CVE database downloads);
+  - git / GitHub (working directory; gh needs auth and a GitHub remote):
+    git_repo_status, git_log, git_diff, gh_prs, and GitHub Actions via gh:
+    gh_runs, gh_run_view (one run's jobs/steps), gh_workflows;
+  - Cloud identity (read-only): aws_identity (account + principal),
+    gcloud_identity (account/project/region), az_account (subscription),
+    az_groups (resource groups);
+  - Monitoring/logging (only if the operator set the endpoint env vars):
+    prom_query (instant PromQL), loki_query (instant LogQL),
+    grafana_health;
+  - New Relic (only if NEW_RELIC_API_KEY + NEW_RELIC_ACCOUNT_ID are set):
+    newrelic_nrql (NRQL over APM/infra data), newrelic_alerts (open alert
+    incidents);
+  - Ansible (listing only): ansible_inventory (resolved hosts/groups),
+    ansible_playbook_tasks (what a playbook WOULD do).
+  When a question can be answered with real evidence from an available tool,
+  call the tool instead of answering from memory. Pick the most direct
+  read-only inspection that answers the question.
+- All tools are READ-ONLY. Do not suggest actions as if you could perform
+  them: there is no delete, restart, edit, apply, scale, exec, create, run,
+  rm, pull, push, commit, reset, or destroy capability anywhere. The
+  Kubernetes tools only run the get/logs/top verbs and a config get-contexts
+  listing; the Ansible tools only list; the monitoring tools only GET.
+- kubectl needs a configured cluster context; docker needs the daemon
+  running; terraform tools operate on the working directory the agent was
+  launched from; git/gh tools on the repository there. If a CLI is missing,
+  misconfigured, unauthenticated, or the target is unreachable, report the
+  EXACT error you received — never invent pod state, log lines, state, or
+  CI results.
+- The result of a tool call is REAL output produced by the application.
+  Quote and summarize it faithfully; never invent, pad, or "correct" numbers
+  or lines, and never describe output you did not actually receive.
+- If a tool errors, report the error honestly and adapt — re-request it with
+  valid arguments, or tell the user what went wrong.
+- Monitoring tools (prom_query, loki_query, grafana_health) only work when
+  the operator has set PROMETHEUS_URL / LOKI_URL / GRAFANA_URL. If such a
+  tool reports a missing endpoint, tell the user which environment variable
+  to set — never invent a URL or pretend you queried one. The same applies
+  to New Relic (NEW_RELIC_API_KEY + NEW_RELIC_ACCOUNT_ID).
+- Cloud tools (aws_identity, gcloud_identity, az_account, az_groups) need
+  the respective CLI installed and authenticated; Ansible tools
+  (ansible_inventory, ansible_playbook_tasks) list only — inventory and
+  playbook tasks, never a playbook run. Security, GitOps and mesh tools
+  (trivy_image_scan, helm_list/status/history, argocd_apps/app_status,
+  istioctl_proxy_status) need their CLI installed (trivy, helm, argocd,
+  istioctl) — report missing/misconfigured CLIs exactly as the error says.
+
+INVESTIGATING PROBLEMS (Phase 4)
+
+- When the user reports a concrete problem or anomaly (a failing pod, a
+  broken rollout, an alert, a degradation) — NOT a general question — open a
+  formal investigation first: call investigation_begin with a one-line
+  problem statement and 2-4 initial hypotheses. Then drive the
+  investigation deliberately.
+- Track as you go: each piece of real tool evidence goes into the record
+  with investigation_record (kind=evidence, linking it to a hypothesis when
+  it bears on one), and update each hypothesis's verdict as evidence builds
+  (kind=verdict, status supported/refuted/confirmed). The tracker returns
+  with every record call so you always see the live state.
+- Only conclude (investigation_conclude) when the evidence is sufficient:
+  name the root cause, remediation RECOMMENDATIONS — you never execute
+  anything; state them as proposals — verification steps, and your
+  confidence. Then end your answer with the structured report:
+  Facts → Hypotheses (with status) → Root cause → Remediation
+  (recommended) → Verification steps.
+- If evidence is insufficient, say exactly what is unknown and what would
+  resolve it. Never guess a root cause to fill the report.
+- The investigation tools persist the record in memory only; nothing you
+  record changes any real system.
+"""

agent/store.py

@@ -0,0 +1,147 @@
+"""Investigation persistence (Phase 7): the record survives CLI exits.
+
+One JSON file per investigation, written atomically (tmp file + rename)
+into a directory — by default ~/.devops-ai-agent/investigations/, kept out
+of any working directory so records never pollute a repo. Every save
+rewrites the active record's file in place, so the directory holds one
+file per investigation (not per change) and a crash mid-investigation
+loses nothing.
+
+Best-effort by design: an unwritable directory, a full disk, or a corrupt
+file degrades to "persistence unavailable / skipped" and never interrupts
+an investigation. Pure stdlib — json, pathlib, datetime.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import re
+from pathlib import Path
+
+from agent.investigation import Investigation, InvestigationError
+
+# Default location; AGENT_STORE_DIR (or --store-dir) overrides it.
+DEFAULT_DIR = Path.home() / ".devops-ai-agent" / "investigations"
+
+
+def _slug(text: str, limit: int = 40) -> str:
+    """Filename-safe slug of the problem statement."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug[:limit].rstrip("-") or "investigation"
+
+
+class InvestigationStore:
+    """Writes investigation records to disk and reads them back."""
+
+    def __init__(self, directory: str | os.PathLike) -> None:
+        self.directory = Path(directory).expanduser()
+        # File the active record is persisted to; fixed at first save so
+        # every subsequent save updates the same file in place.
+        self._current_path: Path | None = None
+
+    # --- write path -----------------------------------------------------------
+
+    @property
+    def current_file(self) -> str | None:
+        """Name of the file the active record is saved to, if any."""
+        return self._current_path.name if self._current_path else None
+
+    def save(self, inv: Investigation) -> Path | None:
+        """Persist `inv`, creating its file on first save.
+
+        Returns the file path, or None when the store is unusable. Never
+        raises — persistence must not be able to break an investigation.
+        """
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            if self._current_path is None:
+                stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+                self._current_path = self._collision_free(
+                    f"{stamp}-{_slug(inv.problem)}"
+                )
+            payload = inv.to_dict(
+                saved_at=datetime.datetime.now().isoformat(timespec="seconds")
+            )
+            tmp = self._current_path.with_name(self._current_path.name + ".tmp")
+            tmp.write_text(
+                json.dumps(payload, indent=2, ensure_ascii=False),
+                encoding="utf-8",
+            )
+            tmp.replace(self._current_path)
+            return self._current_path
+        except OSError:
+            return None
+
+    def forget(self) -> None:
+        """Stop tracking the active file (the saved copy remains as history)."""
+        self._current_path = None
+
+    def _collision_free(self, base: str) -> Path:
+        path = self.directory / f"{base}.json"
+        n = 2
+        while path.exists():
+            path = self.directory / f"{base}-{n}.json"
+            n += 1
+        return path
+
+    # --- read path ------------------------------------------------------------
+
+    def resume_latest(self) -> Investigation | None:
+        """Newest in-progress record, or None. Concluded and corrupt files
+        are skipped. Remembers the file so subsequent saves update it."""
+        for path in self._saved_files():
+            data = self._read(path)
+            if data is None or data.get("status") != "in_progress":
+                continue
+            inv = self._parse(data)
+            if inv is not None:
+                self._current_path = path
+                return inv
+        return None
+
+    def list_saved(self) -> list[dict]:
+        """Every saved record, newest first: file, problem, status, saved_at."""
+        rows = []
+        for path in self._saved_files():
+            data = self._read(path)
+            if data is None:
+                continue
+            rows.append(
+                {
+                    "file": path.name,
+                    "problem": str(data.get("problem", "(unknown)")),
+                    "status": str(data.get("status", "unknown")),
+                    "saved_at": str(data.get("saved_at", "")),
+                }
+            )
+        return rows
+
+    def _saved_files(self) -> list[Path]:
+        try:
+            files = [p for p in self.directory.glob("*.json") if p.is_file()]
+        except OSError:
+            return []
+        # Timestamp-prefixed names: lexical order == chronological order.
+        return sorted(files, reverse=True)
+
+    def _read(self, path: Path) -> dict | None:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        return data if isinstance(data, dict) else None
+
+    def _parse(self, data: dict) -> Investigation | None:
+        try:
+            return Investigation.from_dict(data)
+        except (InvestigationError, KeyError, TypeError, ValueError,
+                AttributeError):
+            return None
+
+
+def default_store() -> InvestigationStore:
+    """Store at the default location; AGENT_STORE_DIR overrides it."""
+    override = os.getenv("AGENT_STORE_DIR")
+    return InvestigationStore(override or DEFAULT_DIR)