kubeintellect 2.0.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
app/__init__.py ADDED
File without changes
app/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from app.cli import main
2
+
3
+ main()
app/agent/__init__.py ADDED
File without changes
app/agent/hitl.py ADDED
@@ -0,0 +1,21 @@
1
+ """
2
+ HITL approval/denial detection — pure string matching, no infrastructure.
3
+ Imported by workflow.py and testable without any LangGraph/Postgres setup.
4
+ """
5
+
6
+ _APPROVAL_PHRASES = {
7
+ "yes", "approve", "approved", "do it", "yes do it",
8
+ "go ahead", "confirm", "ok", "okay", "sure", "proceed", "run it",
9
+ }
10
+ _DENIAL_PHRASES = {
11
+ "no", "deny", "denied", "cancel", "abort",
12
+ "stop", "nope", "don't", "dont",
13
+ }
14
+
15
+
16
+ def is_approval(message: str) -> bool:
17
+ return message.strip().lower() in _APPROVAL_PHRASES
18
+
19
+
20
+ def is_denial(message: str) -> bool:
21
+ return message.strip().lower() in _DENIAL_PHRASES
File without changes
@@ -0,0 +1,229 @@
1
+ """Coordinator node — decides whether to answer directly or fan-out to RCA subagents."""
2
+ from __future__ import annotations
3
+
4
+ import time
5
+
6
+ from langchain_core.messages import AIMessage, SystemMessage
7
+ from langchain_core.runnables import RunnableConfig
8
+
9
+ from app.agent.state import AgentState
10
+ from app.core.llm import get_coordinator_llm
11
+ from app.streaming.emitter import StatusEvent, emit
12
+ from app.tools.registry import ALL_TOOLS
13
+ from app.utils.logger import get_logger
14
+
15
+ logger = get_logger(__name__)
16
+
17
+ _COORDINATOR_SYSTEM = """\
18
+ You are KubeIntellect, an expert Kubernetes operations AI.
19
+
20
+ You have access to three tools:
21
+ - run_kubectl: run any kubectl command against the cluster
22
+ - query_prometheus: query Prometheus metrics (PromQL)
23
+ - query_loki: query Loki for application logs (LogQL)
24
+
25
+ Tool-selection by time intent — CRITICAL:
26
+
27
+ "Current / active issues" (no time qualifier, or "now", "today"):
28
+ - Use kubectl get pods --all-namespaces → shows live state only.
29
+ - kubectl describe pod → shows Last State (exit reason + timestamp).
30
+ - query_prometheus(range_minutes=0) → current metric snapshot (optional).
31
+ - Do NOT use range_minutes>0 or query_loki for this case: they surface
32
+ already-resolved problems and produce false positives.
33
+
34
+ "Historical issues" (user says "last N hours/days", "yesterday", "last night"):
35
+ - query_prometheus with range_minutes matching the window:
36
+ increase(kube_pod_container_status_restarts_total[Nm]) ← pods that restarted
37
+ kube_pod_container_status_last_terminated_reason ← termination cause
38
+ - query_loki with since="Nh" or since="Nd" → logs from that window.
39
+ - kubectl describe pod → still useful for Last State timestamps.
40
+ - Do NOT rely on kubectl get pods for history: it shows only current state.
41
+
42
+ "Pods with issues" (no qualifier) means pods NOT in a desired state RIGHT NOW:
43
+ - Non-Running phases: CrashLoopBackOff, Error, OOMKilled, ImagePullBackOff,
44
+ Pending (stuck), Terminating (stuck), ContainerCreating (stuck).
45
+ - kubectl get pods --all-namespaces is the correct and sufficient tool.
46
+
47
+ For SIMPLE questions (cluster info, status checks, single-resource lookups):
48
+ Answer directly using tools as needed.
49
+ When the user asks to list or get resources (pods, nodes, deployments, etc.),
50
+ always show the COMPLETE raw output in a code block — never summarize or omit rows.
51
+
52
+ For COMPLEX root-cause analysis (pod crashes, service outages, performance degradation):
53
+ Respond with EXACTLY: "RCA_REQUIRED"
54
+ The system will automatically dispatch 4 specialist subagents in parallel.
55
+
56
+ When synthesizing subagent findings (messages contain <findings> XML):
57
+ Produce a comprehensive root-cause analysis with a concrete fix recommendation.
58
+ Be specific: name the exact resource, namespace, and remediation command.
59
+
60
+ IMPORTANT — Truncated output:
61
+ If any tool output contains a truncation marker (text like "[truncated" or "chars omitted"),
62
+ you MUST include a visible warning in your response, for example:
63
+ "> ⚠️ Output was truncated — use narrower filters (e.g. `-n <namespace>`, `-l <label>`, `--tail`) to see the full result."
64
+ Never silently drop this warning. The user must know the list is incomplete.
65
+ """
66
+
67
+
68
+ async def coordinator(state: AgentState, config: RunnableConfig = None) -> dict:
69
+ """
70
+ Coordinator node. Always returns a plain state-update dict — never Send objects.
71
+
72
+ Two modes:
73
+ - Decision : no findings yet → ask the LLM; if it says RCA_REQUIRED set the flag.
74
+ - Synthesis : findings present → synthesize them into a final RCAResult.
75
+
76
+ The fan-out itself is the responsibility of route_coordinator (workflow.py), which
77
+ reads the rca_required flag and returns list[Send] for LangGraph to execute.
78
+ """
79
+ session_id = state.get("session_id", "-")
80
+ user_id = state.get("user_id", "-")
81
+
82
+ # ── Synthesis mode: subagent findings are ready ───────────────────────────
83
+ if state.get("findings"):
84
+ logger.debug(f"coordinator: synthesizing {len(state['findings'])} findings session={session_id}")
85
+ await emit(session_id, StatusEvent(
86
+ phase="synthesizing",
87
+ message="Synthesizing specialist findings…",
88
+ session_id=session_id,
89
+ ))
90
+ return await _synthesize(state)
91
+
92
+ # ── Decision mode: ask the LLM ────────────────────────────────────────────
93
+ await emit(session_id, StatusEvent(
94
+ phase="analyzing",
95
+ message="Analyzing your request…",
96
+ session_id=session_id,
97
+ ))
98
+
99
+ last_user_msg = ""
100
+ for m in reversed(state.get("messages", [])):
101
+ if hasattr(m, "type") and m.type == "human":
102
+ last_user_msg = m.content[:120]
103
+ break
104
+ logger.debug(f"coordinator: invoking LLM user={user_id} session={session_id} msg={last_user_msg!r}")
105
+
106
+ t0 = time.monotonic()
107
+ try:
108
+ result = await _direct_answer(state, config=config)
109
+ except Exception as exc:
110
+ logger.error(f"coordinator: LLM call failed session={session_id} error={exc!r}")
111
+ raise
112
+ elapsed = time.monotonic() - t0
113
+
114
+ last = result["messages"][-1].content.strip() if result.get("messages") else ""
115
+ is_rca = last == "RCA_REQUIRED"
116
+ logger.debug(
117
+ f"coordinator: LLM responded in {elapsed:.2f}s session={session_id} "
118
+ f"decision={'RCA' if is_rca else 'direct'}"
119
+ )
120
+
121
+ if is_rca:
122
+ logger.info("coordinator: LLM requested RCA — setting rca_required flag for fan-out")
123
+ await emit(session_id, StatusEvent(
124
+ phase="dispatching",
125
+ message="Dispatching specialist subagents (pod · metrics · logs · events)…",
126
+ session_id=session_id,
127
+ ))
128
+ # Do NOT add the "RCA_REQUIRED" sentinel text to message history.
129
+ # route_coordinator reads rca_required and issues the Send fan-out.
130
+ return {"rca_required": True}
131
+
132
+ return result
133
+
134
+
135
+ async def _direct_answer(state: AgentState, config: RunnableConfig = None) -> dict:
136
+ """Run coordinator LLM with tools for simple queries."""
137
+ from langgraph.prebuilt import create_react_agent
138
+
139
+ memory_context = state.get("memory_context", "")
140
+ system_parts = [_COORDINATOR_SYSTEM]
141
+ if memory_context:
142
+ system_parts.append(f"\n\n## Cluster Context\n{memory_context}")
143
+
144
+ llm = get_coordinator_llm()
145
+ agent = create_react_agent(llm, tools=ALL_TOOLS)
146
+
147
+ input_messages = [SystemMessage(content="\n".join(system_parts))] + list(state["messages"])
148
+ result = await agent.ainvoke({"messages": input_messages}, config=config)
149
+
150
+ new_messages = result["messages"][len(input_messages):]
151
+ tool_calls = sum(1 for m in new_messages if hasattr(m, "tool_calls") and m.tool_calls)
152
+ logger.debug(
153
+ f"coordinator: direct answer complete new_msgs={len(new_messages)} tool_calls={tool_calls}"
154
+ )
155
+ return {"messages": new_messages}
156
+
157
+
158
+ async def _synthesize(state: AgentState) -> dict:
159
+ """Synthesize subagent findings into a final RCAResult."""
160
+ import json
161
+
162
+ from langchain_core.messages import HumanMessage
163
+
164
+ from app.agent.state import RCAResult
165
+
166
+ findings = state["findings"]
167
+ findings_xml = "\n".join(
168
+ f"<finding domain='{f.domain}' confidence='{f.confidence}'>\n"
169
+ f" hypothesis: {f.hypothesis}\n"
170
+ f" signals: {', '.join(f.signals)}\n"
171
+ f" evidence: {chr(10).join(f.evidence[:3])}\n"
172
+ f"</finding>"
173
+ for f in findings
174
+ )
175
+
176
+ synthesis_prompt = f"""
177
+ You have received findings from 4 specialist subagents:
178
+
179
+ <findings>
180
+ {findings_xml}
181
+ </findings>
182
+
183
+ Synthesize these into a single root-cause analysis. Respond with ONLY a JSON object:
184
+ {{
185
+ "root_cause": "<single-sentence root cause>",
186
+ "confidence": <0.0-1.0>,
187
+ "supporting_evidence": ["<evidence 1>", ...],
188
+ "conflicting_evidence": ["<conflict 1>" or []],
189
+ "reasoning": "<chain-of-thought over the findings>",
190
+ "recommended_fix": "<concrete kubectl/config fix>",
191
+ "affected_domain": ["<domain>", ...]
192
+ }}
193
+ """
194
+
195
+ llm = get_coordinator_llm()
196
+ response = await llm.ainvoke(
197
+ [SystemMessage(content=_COORDINATOR_SYSTEM), HumanMessage(content=synthesis_prompt)]
198
+ )
199
+
200
+ raw = response.content.strip()
201
+ if raw.startswith("```"):
202
+ raw = raw.split("```")[1]
203
+ if raw.startswith("json"):
204
+ raw = raw[4:]
205
+
206
+ try:
207
+ rca = RCAResult.model_validate(json.loads(raw.strip()))
208
+ except Exception as exc:
209
+ logger.warning(f"coordinator: failed to parse RCA JSON — {exc}")
210
+ rca = RCAResult(
211
+ root_cause="Synthesis failed — see individual findings",
212
+ confidence=0.0,
213
+ supporting_evidence=[f.hypothesis for f in findings],
214
+ reasoning=f"Parse error: {exc}",
215
+ recommended_fix="Review findings manually",
216
+ )
217
+
218
+ summary = (
219
+ f"**Root Cause**: {rca.root_cause}\n\n"
220
+ f"**Confidence**: {rca.confidence:.0%}\n\n"
221
+ f"**Recommended Fix**: {rca.recommended_fix}\n\n"
222
+ f"**Reasoning**: {rca.reasoning}"
223
+ )
224
+
225
+ return {
226
+ "rca_result": rca,
227
+ "rca_required": False,
228
+ "messages": [AIMessage(content=summary)],
229
+ }
@@ -0,0 +1,31 @@
1
+ """memory_loader node — async DB reads pinned into coordinator SystemMessage."""
2
+ from __future__ import annotations
3
+
4
+ from langchain_core.messages import SystemMessage
5
+
6
+ from app.agent.state import AgentState
7
+ from app.db.memory_store import load_memory_context
8
+ from app.streaming.emitter import StatusEvent, emit
9
+ from app.utils.logger import get_logger
10
+
11
+ logger = get_logger(__name__)
12
+
13
+
14
+ async def memory_loader(state: AgentState) -> dict:
15
+ """Load user prefs, failure hints, past RCA, runbooks into memory_context."""
16
+ session_id = state["session_id"]
17
+ user_id = state["user_id"]
18
+
19
+ await emit(session_id, StatusEvent(
20
+ phase="loading",
21
+ message="Loading conversation context…",
22
+ session_id=session_id,
23
+ ))
24
+
25
+ logger.debug(f"memory_loader: loading context for user={user_id} session={session_id}")
26
+
27
+ context = await load_memory_context(user_id=user_id, session_id=session_id)
28
+
29
+ # findings=None triggers _findings_reducer's reset path, clearing any
30
+ # stale findings that accumulated during a previous RCA in this session.
31
+ return {"memory_context": context, "findings": None}
@@ -0,0 +1,117 @@
1
+ """RCA specialist subagent — one domain, ReAct loop, structured AgentFinding output."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+
6
+ from langchain_core.messages import SystemMessage
7
+ from langgraph.prebuilt import create_react_agent
8
+
9
+ from app.agent.state import AgentFinding, SubagentInput
10
+ from app.core.llm import get_subagent_llm
11
+ from app.tools.registry import ALL_TOOLS
12
+ from app.utils.logger import get_logger
13
+
14
+ logger = get_logger(__name__)
15
+
16
+ # Each ReAct step consumes ~3 recursion units (LLM call + tool call + tool response).
17
+ # Allow up to ~16 tool calls per subagent before giving up.
18
+ _SUBAGENT_RECURSION_LIMIT = 50
19
+
20
+ _DOMAIN_PROMPTS: dict[str, str] = {
21
+ "pod": (
22
+ "You are a Kubernetes pod-health specialist. "
23
+ "Investigate pod status, container restarts, OOMKilled events, "
24
+ "image pull errors, readiness/liveness probe failures, and resource limits. "
25
+ "Use kubectl (get pods --all-namespaces, describe pod, logs) to gather evidence. "
26
+ "Limit yourself to at most 6 tool calls — focus on the most suspicious pods first."
27
+ ),
28
+ "metrics": (
29
+ "You are a Kubernetes metrics specialist. "
30
+ "Investigate CPU/memory usage, HPA scaling events, throttling, "
31
+ "and resource saturation via Prometheus queries. "
32
+ "Look for anomalies in the last 30 minutes (use range_minutes=30). "
33
+ "Use instant queries (range_minutes=0) for current resource utilisation. "
34
+ "Limit yourself to at most 6 Prometheus queries — prioritise high-level signals first."
35
+ ),
36
+ "logs": (
37
+ "You are a Kubernetes application-log specialist. "
38
+ "Investigate recent error/warning log lines from affected pods via Loki. "
39
+ "Identify error patterns, stack traces, and timing correlations.\n\n"
40
+ "IMPORTANT — query efficiency:\n"
41
+ " Use a single broad query that covers all namespaces at once, for example:\n"
42
+ " {namespace=~\".+\"} |= `ERROR` \n"
43
+ " or target the most relevant namespace first:\n"
44
+ " {namespace=\"kubeintellect\"} |= `ERROR`\n"
45
+ " Do NOT query each namespace in a separate call. "
46
+ "Limit yourself to at most 4 Loki queries total."
47
+ ),
48
+ "events": (
49
+ "You are a Kubernetes cluster-events specialist. "
50
+ "Investigate warning events, scheduler failures, node pressure, "
51
+ "PVC binding issues, and network policy rejections via kubectl events. "
52
+ "Use 'kubectl get events --all-namespaces' as your first call to get a full picture. "
53
+ "Limit yourself to at most 5 tool calls."
54
+ ),
55
+ }
56
+
57
+ _FINDING_SCHEMA_HINT = """
58
+ After your investigation, respond with a JSON object matching this schema:
59
+ {
60
+ "domain": "<your domain>",
61
+ "signals": ["<key signal 1>", ...],
62
+ "hypothesis": "<root-cause hypothesis>",
63
+ "confidence": <0.0-1.0>,
64
+ "evidence": ["<verbatim excerpt 1>", ...],
65
+ "tool_calls_made": ["<tool(args)>", ...]
66
+ }
67
+ Respond with ONLY the JSON object, no markdown fences.
68
+ """
69
+
70
+
71
+ async def run_subagent(payload: SubagentInput) -> AgentFinding:
72
+ """Execute one specialist subagent and return a structured AgentFinding."""
73
+ domain = payload["domain"]
74
+ messages = payload["messages"]
75
+ memory_context = payload.get("memory_context", "")
76
+
77
+ logger.debug(f"subagent [{domain}]: starting investigation")
78
+
79
+ system_parts = [_DOMAIN_PROMPTS[domain]]
80
+ if memory_context:
81
+ system_parts.append(f"\n\n## Cluster Context\n{memory_context}")
82
+ system_parts.append(_FINDING_SCHEMA_HINT)
83
+ system_prompt = "\n".join(system_parts)
84
+
85
+ llm = get_subagent_llm()
86
+ agent = create_react_agent(llm, tools=ALL_TOOLS)
87
+
88
+ input_messages = [SystemMessage(content=system_prompt)] + list(messages)
89
+
90
+ result = await agent.ainvoke(
91
+ {"messages": input_messages},
92
+ config={"recursion_limit": _SUBAGENT_RECURSION_LIMIT},
93
+ )
94
+
95
+ # Extract the last AI message text as the finding JSON
96
+ last_msg = result["messages"][-1]
97
+ raw_content = last_msg.content if hasattr(last_msg, "content") else str(last_msg)
98
+
99
+ try:
100
+ clean = raw_content.strip()
101
+ if clean.startswith("```"):
102
+ clean = clean.split("```")[1]
103
+ if clean.startswith("json"):
104
+ clean = clean[4:]
105
+ finding = AgentFinding.model_validate(json.loads(clean.strip()))
106
+ except Exception as exc:
107
+ logger.warning(f"subagent [{domain}]: failed to parse finding JSON — {exc}")
108
+ finding = AgentFinding(
109
+ domain=domain,
110
+ signals=["(parse error)"],
111
+ hypothesis="Could not parse subagent response",
112
+ confidence=0.0,
113
+ evidence=[raw_content[:500]],
114
+ )
115
+
116
+ logger.debug(f"subagent [{domain}]: confidence={finding.confidence:.2f}")
117
+ return finding
app/agent/state.py ADDED
@@ -0,0 +1,95 @@
1
+ """LangGraph state types for KubeIntellect V2."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Annotated, Any
5
+
6
+ from langchain_core.messages import BaseMessage
7
+ from langgraph.graph.message import add_messages
8
+ from pydantic import BaseModel, Field
9
+ from typing_extensions import TypedDict
10
+
11
+
12
+ def _findings_reducer(left: list, right: list | None) -> list:
13
+ """Accumulate subagent findings from parallel fan-out.
14
+
15
+ ``None`` is the reset sentinel: emitted by memory_loader at the start of
16
+ every turn so stale findings from a prior RCA never bleed into the next.
17
+ A normal list (including ``[]``) is appended so all 4 parallel subagents
18
+ contribute their finding correctly.
19
+ """
20
+ if right is None:
21
+ return []
22
+ return (left or []) + right
23
+
24
+
25
+ # ── Subagent structured output ────────────────────────────────────────────────
26
+
27
+
28
+ class AgentFinding(BaseModel):
29
+ """Structured finding from one RCA specialist subagent."""
30
+ domain: str = Field(description="Specialist domain: pod | metrics | logs | events")
31
+ signals: list[str] = Field(description="Key signals observed (kubectl/prometheus/loki output highlights)")
32
+ hypothesis: str = Field(description="Root-cause hypothesis for this domain")
33
+ confidence: float = Field(ge=0.0, le=1.0, description="Confidence score 0-1")
34
+ evidence: list[str] = Field(description="Verbatim excerpts or metric values supporting the hypothesis")
35
+ tool_calls_made: list[str] = Field(default_factory=list, description="Tools invoked by this subagent")
36
+
37
+
38
+ # ── Synthesizer structured output ─────────────────────────────────────────────
39
+
40
+
41
+ class RCAResult(BaseModel):
42
+ """Final synthesized RCA from the coordinator."""
43
+ root_cause: str = Field(description="Single-sentence root cause statement")
44
+ confidence: float = Field(ge=0.0, le=1.0)
45
+ supporting_evidence: list[str]
46
+ conflicting_evidence: list[str] = Field(default_factory=list)
47
+ reasoning: str = Field(description="Chain-of-thought reasoning over the subagent findings")
48
+ recommended_fix: str = Field(description="Concrete kubectl/config fix recommendation")
49
+ affected_domain: list[str] = Field(default_factory=list, description="Which domains contributed")
50
+
51
+
52
+ # ── Main graph state ───────────────────────────────────────────────────────────
53
+
54
+
55
+ class AgentState(TypedDict):
56
+ """State carried through the KubeIntellect coordinator graph."""
57
+ # Message history — LangGraph reducer appends new messages automatically
58
+ messages: Annotated[list[BaseMessage], add_messages]
59
+
60
+ # Loaded from DB before coordinator runs (pinned system context)
61
+ memory_context: str
62
+
63
+ # Subagent findings accumulated via parallel fan-out.
64
+ # Uses _findings_reducer so all 4 subagents contribute (not last-write-wins)
65
+ # and memory_loader can reset with None between turns.
66
+ findings: Annotated[list[AgentFinding], _findings_reducer]
67
+
68
+ # Set by coordinator when the LLM requests a parallel RCA fan-out.
69
+ # Consumed by route_coordinator to dispatch the 4 specialist subagents.
70
+ # Reset to False by the per-turn initial state (no reducer → plain overwrite).
71
+ rca_required: bool
72
+
73
+ # Final RCA (set by synthesizer node, None until synthesis is done)
74
+ rca_result: RCAResult | None
75
+
76
+ # HITL state — set when run_kubectl raises HITLRequired
77
+ pending_hitl: dict[str, Any] | None # {action_id, command, risk_level, human_summary}
78
+
79
+ # Conversation / session metadata
80
+ session_id: str
81
+ user_id: str
82
+ user_role: str # "admin" | "readonly" — injected by API auth layer
83
+
84
+
85
+ # ── Subagent-scoped state (used in Send payload) ───────────────────────────────
86
+
87
+
88
+ class SubagentInput(TypedDict):
89
+ """Payload sent to each specialist subagent via Send API."""
90
+ domain: str # pod | metrics | logs | events
91
+ session_id: str
92
+ user_id: str
93
+ user_role: str # "admin" | "readonly"
94
+ messages: list[BaseMessage]
95
+ memory_context: str