devopsiq 0.1.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,5 @@
+"""Agent package.
+
+Phase 2: the DevOpsAgent holds the system prompt + conversation history and
+runs the tool-use loop (see agent.py and the tool registry in tools/).
+"""

agent/agent.py

@@ -0,0 +1,232 @@
+"""Core agent: the conversation + tool-use loop to the LLM backend.
+
+Phase 2 builds the tool-use loop on top of the Phase 1 skeleton, Phase 4
+adds the investigation loop on top of that, and Phase 5 broadens coverage
+from Kubernetes-only to the wider DevOps surface:
+
+    user reports a problem
+      -> the model opens an investigation (investigation_begin)
+      -> it gathers evidence with the read-only tools — Kubernetes,
+         Linux systemd/journal/journal/ports/processes, Docker containers,
+         Terraform state/plan, git/gh — tracking hypotheses and evidence in
+         a first-class record (investigation_record)
+      -> it concludes with root cause + remediation + verification
+         (investigation_conclude), ending with a structured report
+
+The tool-use loop itself is unchanged: every model call funnels through the
+single `_complete()` chokepoint, and the investigation tools are just three
+more registered tools — they persist state in agent/investigation.py, which
+mutates nothing outside the agent's own memory. The read-only guarantee
+holds: every tool is a fixed, allowlisted argv template; no tool can touch
+a cluster, a file, or infrastructure beyond reading it.
+
+Phase 7 makes that record durable: every mutation is auto-saved to the
+InvestigationStore (agent/store.py), so the investigation survives CLI
+exits; the delegates below expose resume/list/store-location to the CLI.
+"""
+
+import os
+
+from openai import OpenAI
+
+from agent.prompts import SYSTEM_PROMPT
+from agent.store import InvestigationStore
+from tools import (  # noqa: F401 — side effect: each module registers its tools
+    ansible,
+    argocd,
+    cloud,
+    docker,
+    git_ci,
+    helm,
+    investigation,
+    istio,
+    kubernetes,
+    monitoring,
+    newrelic,
+    preflight,
+    system,
+    terraform,
+    trivy,
+)
+from tools.investigation import (
+    finish_investigation,
+    list_saved_text,
+    report_json,
+    report_text,
+    resume_investigation as load_resumable_investigation,
+    set_store as set_investigation_store,
+    start_investigation,
+    status_text,
+    store_directory_text,
+)
+from tools.registry import execute_tool, get_tools
+
+DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_MODEL = "z-ai/glm-5.3"
+PLACEHOLDER_KEY = "your_key_here"
+
+# Safety valve: the model gets at most this many tool-use turns before we stop.
+MAX_TOOL_ITERATIONS = 10
+
+
+class DevOpsAgent:
+    """Minimal DevOps investigation assistant (read-only by design)."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        # Configuration resolution order: explicit argument > environment > default.
+        self.api_key = api_key or os.getenv("OPENROUTER_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "OPENROUTER_API_KEY is not set. Copy .env.example to .env and "
+                "fill in your key, or export OPENROUTER_API_KEY in your shell."
+            )
+        if self.api_key.strip().lower() == PLACEHOLDER_KEY:
+            raise ValueError(
+                "OPENROUTER_API_KEY still has the placeholder value. Edit .env "
+                "and replace `your_key_here` with your real key."
+            )
+
+        self.model = model or os.getenv("OPENROUTER_MODEL", DEFAULT_MODEL)
+        self.base_url = base_url or os.getenv("OPENROUTER_BASE_URL", DEFAULT_BASE_URL)
+
+        # OpenRouter exposes an OpenAI-compatible API, so the official OpenAI
+        # SDK is a drop-in client — just pointed at OpenRouter's base URL.
+        self.client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+
+        # Short-term conversation history. Starts with the system prompt;
+        # grows as user, model, and tool results exchange turns.
+        self.messages: list[dict] = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+        # Tools the model may call this session (read-only by construction).
+        self.tools = get_tools()
+
+    def ask(self, user_message: str) -> str:
+        """Send one user message; run the tool-use loop; return the final answer.
+
+        The message, any tool exchanges, and the final assistant reply are all
+        kept in this session's history so the model retains context across
+        turns. Raises ValueError on empty input.
+        """
+        message = user_message.strip()
+        if not message:
+            raise ValueError("Cannot send an empty user message.")
+
+        self.messages.append({"role": "user", "content": message})
+        reply = self._complete()
+        self.messages.append({"role": "assistant", "content": reply})
+        return reply
+
+    # --- investigation lifecycle (Phase 4) — thin CLI-facing delegates --------
+    #
+    # The investigation record itself lives in agent/investigation.py; the
+    # model drives it via the investigation_* tools inside the normal loop.
+    # These methods let the CLI inspect and control the same state (/investigate,
+    # /investigation, /report, /endinvestigation).
+
+    def begin_investigation(self, problem: str) -> str:
+        """Open a formal investigation for `problem` (the /investigate command)."""
+        return start_investigation(problem)
+
+    def investigation_status_text(self) -> str | None:
+        """Live tracker text, or None when no investigation is active."""
+        return status_text()
+
+    def investigation_report_text(self) -> str | None:
+        """Canonical report once concluded (tracker while in progress), or None."""
+        return report_text()
+
+    def investigation_report_json(self) -> dict | None:
+        """Structured JSON export of the investigation (for CI/automation), or None."""
+        return report_json()
+
+    def end_investigation(self) -> str:
+        """Clear the active investigation (read-only: discards only memory)."""
+        return finish_investigation()
+
+    # --- persistence (Phase 7) — thin CLI-facing delegates ---------------------
+    #
+    # The record is auto-saved by the mutation chokepoint in
+    # tools/investigation.py; these methods expose resume/list/store-location
+    # to the CLI (REPL startup auto-resume, /investigations, --store-dir).
+
+    @property
+    def store_dir(self) -> str | None:
+        """Directory records are saved to, or None when persistence is off."""
+        return store_directory_text()
+
+    def list_investigations(self) -> str | None:
+        """Saved investigation records, newest first, or None if none."""
+        return list_saved_text()
+
+    def resume_investigation(self) -> str | None:
+        """Continue the newest in-progress record, or None if there is none."""
+        return load_resumable_investigation()
+
+    def use_store_dir(self, directory: str) -> None:
+        """Point persistence at `directory` (--store-dir; tests use tmpdirs)."""
+        set_investigation_store(InvestigationStore(directory))
+
+    def _complete(self) -> str:
+        """The tool-use loop — the single chokepoint where the backend is called.
+
+        Each turn sends the full history (with tool schemas attached when tools
+        are available). If the reply requests tools, every requested tool is
+        executed locally, the results are appended, and the loop calls the
+        model again. Stops when the model answers in plain text, or when the
+        iteration cap is reached.
+        """
+        for _ in range(MAX_TOOL_ITERATIONS):
+            request: dict = {"model": self.model, "messages": self.messages}
+            if self.tools:
+                request["tools"] = [tool.schema() for tool in self.tools]
+
+            response = self.client.chat.completions.create(**request)
+            message = response.choices[0].message
+
+            if not message.tool_calls:
+                content = message.content
+                if content is None:
+                    raise RuntimeError("The model returned an empty response.")
+                return content
+
+            # Echo the assistant tool-request turn verbatim, then answer each
+            # call with a sibling "tool" message referencing its call id.
+            self.messages.append(_echo_tool_request(message))
+            for call in message.tool_calls:
+                result = execute_tool(call.function.name, call.function.arguments)
+                self.messages.append(
+                    {"role": "tool", "tool_call_id": call.id, "content": result}
+                )
+
+        raise RuntimeError(
+            f"The model did not finish after {MAX_TOOL_ITERATIONS} tool-use turns."
+        )
+
+
+def _echo_tool_request(message) -> dict:
+    """Rebuild the assistant turn that requested tools, verbatim.
+
+    The OpenAI-compatible API requires the assistant tool-request turn to be
+    echoed into history with the exact tool_calls, each one answered by a
+    sibling {"role": "tool"} message that references it via tool_call_id.
+    """
+    return {
+        "role": "assistant",
+        "content": message.content or "",
+        "tool_calls": [
+            {
+                "id": call.id,
+                "type": "function",
+                "function": {
+                    "name": call.function.name,
+                    "arguments": call.function.arguments,
+                },
+            }
+            for call in message.tool_calls
+        ],
+    }

agent/investigation.py

@@ -0,0 +1,339 @@
+"""Investigation state for the DevOps agent (Phase 4).
+
+A first-class, in-memory record of an ongoing incident investigation: the
+problem statement, tracked hypotheses with verdicts, evidence notes, and —
+once concluded — root cause, remediation, and verification.
+
+The model drives this state through the investigation_* tools in
+tools/investigation.py; the CLI exposes the same state via /investigate,
+/investigation and /report. This module is PURE DATA — no model calls, no
+I/O — so it is fully unit-testable.
+
+Read-only guarantee: recording a hypothesis or a verdict mutates only this
+agent's in-memory state. Nothing here touches a cluster, a file, or any
+real system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+HYPOTHESIS_STATUSES = ("proposed", "supported", "refuted", "confirmed")
+CONFIDENCE_LEVELS = ("high", "medium", "low")
+
+
+class InvestigationError(Exception):
+    """Raised on invalid state transitions (e.g. unknown hypothesis id)."""
+
+
+@dataclass
+class Hypothesis:
+    id: str
+    statement: str
+    status: str = "proposed"
+    notes: list[str] = field(default_factory=list)
+
+    def set_status(self, status: str) -> None:
+        if status not in HYPOTHESIS_STATUSES:
+            raise InvestigationError(
+                f"invalid hypothesis status {status!r}; expected one of "
+                f"{HYPOTHESIS_STATUSES}"
+            )
+        self.status = status
+
+
+@dataclass
+class EvidenceNote:
+    id: str
+    content: str
+    hypothesis_id: str | None = None  # which tracked hypothesis this bears on
+
+
+@dataclass
+class Conclusion:
+    summary: str
+    root_cause: str
+    remediation: list[str]
+    verification: list[str]
+    confidence: str
+
+
+class Investigation:
+    """Tracks one incident investigation from problem statement to report."""
+
+    def __init__(
+        self,
+        problem: str,
+        initial_hypotheses: list[str] | None = None,
+    ) -> None:
+        if not problem or not problem.strip():
+            raise InvestigationError("problem statement must not be empty")
+        self.problem = problem.strip()
+        self.hypotheses: list[Hypothesis] = []
+        self.evidence: list[EvidenceNote] = []
+        self.conclusion: Conclusion | None = None
+        self._next_h = 1
+        self._next_e = 1
+        for statement in initial_hypotheses or []:
+            if statement and statement.strip():
+                self.add_hypothesis(statement)
+
+    # --- mutations; each returns a short confirmation for the tool result ---
+
+    def add_hypothesis(self, statement: str) -> str:
+        clean = (statement or "").strip()
+        if not clean:
+            raise InvestigationError("hypothesis statement must not be empty")
+        h = Hypothesis(id=f"H{self._next_h}", statement=clean)
+        self._next_h += 1
+        self.hypotheses.append(h)
+        return f"recorded hypothesis {h.id}: {clean}"
+
+    def verify_hypothesis(
+        self, hypothesis_id: str, status: str, note: str | None = None
+    ) -> str:
+        h = self._get_hypothesis(hypothesis_id)
+        h.set_status(status)
+        if note and note.strip():
+            h.notes.append(note.strip())
+        detail = f" — {note.strip()}" if note and note.strip() else ""
+        return f"{h.id} is now [{h.status}]: {h.statement}{detail}"
+
+    def record_evidence(self, content: str, hypothesis_id: str | None = None) -> str:
+        clean = (content or "").strip()
+        if not clean:
+            raise InvestigationError("evidence note must not be empty")
+        if hypothesis_id is not None:
+            self._get_hypothesis(hypothesis_id)  # validates the link target
+        note = EvidenceNote(
+            id=f"E{self._next_e}", content=clean, hypothesis_id=hypothesis_id
+        )
+        self._next_e += 1
+        self.evidence.append(note)
+        link = f" (→ {hypothesis_id})" if hypothesis_id else ""
+        return f"recorded evidence {note.id}: {clean}{link}"
+
+    def conclude(
+        self,
+        *,
+        summary: str,
+        root_cause: str,
+        remediation: str | list[str],
+        verification: str | list[str],
+        confidence: str = "medium",
+    ) -> str:
+        if self.conclusion is not None:
+            return "this investigation is already concluded — /report shows it"
+        if not (summary or "").strip() or not (root_cause or "").strip():
+            raise InvestigationError("summary and root_cause are required")
+        if confidence not in CONFIDENCE_LEVELS:
+            raise InvestigationError(
+                f"invalid confidence {confidence!r}; expected one of {CONFIDENCE_LEVELS}"
+            )
+        self.conclusion = Conclusion(
+            summary=summary.strip(),
+            root_cause=root_cause.strip(),
+            remediation=_string_list(remediation, "remediation"),
+            verification=_string_list(verification, "verification"),
+            confidence=confidence,
+        )
+        return (
+            "investigation concluded. End your answer with the structured "
+            "report; it is also available via /report."
+        )
+
+    # --- read-only views for the model and the CLI ---
+
+    def render_status(self) -> str:
+        """Compact tracker appended to every investigation tool result."""
+        lines = ["**Investigation tracker**", f"Problem: {self.problem}"]
+        if self.conclusion is None:
+            lines.append("Status: in progress")
+        else:
+            lines.append(f"Status: concluded (confidence {self.conclusion.confidence})")
+        if self.hypotheses:
+            lines.append("Hypotheses:")
+            lines += [f"- {h.id} [{h.status}] {h.statement}" for h in self.hypotheses]
+        else:
+            lines.append("Hypotheses: none yet")
+        if self.evidence:
+            lines.append("Evidence:")
+            lines += [
+                f"- {e.id} {e.content}"
+                + (f" (→ {e.hypothesis_id})" if e.hypothesis_id else "")
+                for e in self.evidence
+            ]
+        else:
+            lines.append("Evidence: none recorded yet")
+        return "\n".join(lines)
+
+    def render_report(self) -> str:
+        """Canonical final report (deterministic — always rendered from state)."""
+        if self.conclusion is None:
+            return self.render_status()
+
+        c = self.conclusion
+        lines = [
+            "# Investigation report",
+            "",
+            f"**Problem:** {self.problem}",
+            "",
+            "## Facts / evidence",
+        ]
+        if self.evidence:
+            lines += [
+                f"- {e.content}"
+                + (f" (→ {e.hypothesis_id})" if e.hypothesis_id else "")
+                for e in self.evidence
+            ]
+        else:
+            lines.append("- (none recorded)")
+        lines += ["", "## Hypotheses"]
+        if self.hypotheses:
+            lines += [
+                f"- **{h.id}** [{h.status}] {h.statement}" for h in self.hypotheses
+            ]
+        else:
+            lines.append("- (none)")
+        lines += ["", "## Root cause", "", c.root_cause]
+        lines += ["", "## Remediation (recommendations — nothing was executed)"]
+        lines += [f"- {item}" for item in c.remediation] or ["- (none)"]
+        lines += ["", "## Verification steps"]
+        lines += [f"- {item}" for item in c.verification] or ["- (none)"]
+        lines += [
+            "",
+            f"**Summary:** {c.summary}",
+            f"**Confidence:** {c.confidence}",
+        ]
+        return "\n".join(lines)
+
+    def render_report_json(self) -> dict:
+        """Structured export of the investigation, for CI/automation tooling.
+
+        Always returns the same shape whether or not the investigation is
+        concluded: hypotheses and evidence are lists; `conclusion` is present
+        only once concluded. No model text is trusted — everything is
+        re-derived deterministically from the tracked record.
+        """
+        out: dict = {
+            "problem": self.problem,
+            "status": "concluded" if self.conclusion is not None else "in_progress",
+            "hypotheses": [
+                {
+                    "id": h.id,
+                    "statement": h.statement,
+                    "status": h.status,
+                    "notes": list(h.notes),
+                }
+                for h in self.hypotheses
+            ],
+            "evidence": [
+                {
+                    "id": e.id,
+                    "content": e.content,
+                    "hypothesis_id": e.hypothesis_id,
+                }
+                for e in self.evidence
+            ],
+        }
+        if self.conclusion is not None:
+            c = self.conclusion
+            out["conclusion"] = {
+                "summary": c.summary,
+                "root_cause": c.root_cause,
+                "remediation": list(c.remediation),
+                "verification": list(c.verification),
+                "confidence": c.confidence,
+            }
+        return out
+
+    # --- persistence (Phase 7) — lossless round-trip for the store ------------
+
+    def to_dict(self, *, saved_at: str | None = None) -> dict:
+        """Full serializable state, for the store to write to disk.
+
+        render_report_json() is already a lossless view of the record, so
+        persistence reuses it and adds storage metadata: `schema` (format
+        version, bumped only on breaking changes) and `saved_at` (ISO
+        timestamp, set by the store). from_dict() round-trips this exactly.
+        """
+        out = self.render_report_json()
+        out["schema"] = 1
+        if saved_at is not None:
+            out["saved_at"] = saved_at
+        return out
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Investigation":
+        """Rebuild an Investigation from to_dict() output.
+
+        Tolerant of unknown keys (forward compatible) and strict about our
+        own: a corrupt or truncated file raises InvestigationError (or
+        KeyError for a missing problem), which the store turns into "skip
+        this file" rather than a crash.
+        """
+        inv = cls(data["problem"])
+        for h in data.get("hypotheses") or []:
+            hyp = Hypothesis(
+                id=str(h.get("id", "")),
+                statement=str(h.get("statement", "")),
+                status="proposed",
+                notes=[str(n) for n in (h.get("notes") or [])],
+            )
+            hyp.set_status(str(h.get("status", "proposed")))
+            number = _id_number(hyp.id, "H")
+            if number is None:
+                raise InvestigationError(f"malformed hypothesis id {hyp.id!r}")
+            inv.hypotheses.append(hyp)
+            if number >= inv._next_h:
+                inv._next_h = number + 1
+        for e in data.get("evidence") or []:
+            hypothesis_id = e.get("hypothesis_id")
+            note = EvidenceNote(
+                id=str(e.get("id", "")),
+                content=str(e.get("content", "")),
+                hypothesis_id=str(hypothesis_id) if hypothesis_id else None,
+            )
+            number = _id_number(note.id, "E")
+            if number is None:
+                raise InvestigationError(f"malformed evidence id {note.id!r}")
+            if note.hypothesis_id is not None:
+                inv._get_hypothesis(note.hypothesis_id)  # validate the link
+            inv.evidence.append(note)
+            if number >= inv._next_e:
+                inv._next_e = number + 1
+        c = data.get("conclusion")
+        if c is not None:
+            inv.conclude(
+                summary=str(c.get("summary", "")),
+                root_cause=str(c.get("root_cause", "")),
+                remediation=c.get("remediation") or [],
+                verification=c.get("verification") or [],
+                confidence=str(c.get("confidence", "medium")),
+            )
+        return inv
+
+    def _get_hypothesis(self, hypothesis_id: str) -> Hypothesis:
+        found = next((h for h in self.hypotheses if h.id == hypothesis_id), None)
+        if found is None:
+            raise InvestigationError(
+                f"unknown hypothesis id {hypothesis_id!r}; known ids: "
+                f"{', '.join(h.id for h in self.hypotheses) or 'none'}"
+            )
+        return found
+
+
+def _string_list(value: str | list[str], label: str) -> list[str]:
+    items = [value] if isinstance(value, str) else list(value or [])
+    cleaned = [str(item).strip() for item in items if str(item).strip()]
+    if not cleaned:
+        raise InvestigationError(f"{label} must contain at least one item")
+    return cleaned
+
+
+def _id_number(value: str, prefix: str) -> int | None:
+    """Numeric suffix of an H*/E* id (H12 -> 12), or None if malformed."""
+    if not value.startswith(prefix):
+        return None
+    tail = value[len(prefix):]
+    return int(tail) if tail.isdigit() else None