kubeintellect 2.0.0a1__tar.gz

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.
Files changed (42) hide show
  1. kubeintellect-2.0.0a1/.env.example +121 -0
  2. kubeintellect-2.0.0a1/PKG-INFO +173 -0
  3. kubeintellect-2.0.0a1/README.md +130 -0
  4. kubeintellect-2.0.0a1/app/__init__.py +0 -0
  5. kubeintellect-2.0.0a1/app/__main__.py +3 -0
  6. kubeintellect-2.0.0a1/app/agent/__init__.py +0 -0
  7. kubeintellect-2.0.0a1/app/agent/hitl.py +21 -0
  8. kubeintellect-2.0.0a1/app/agent/nodes/__init__.py +0 -0
  9. kubeintellect-2.0.0a1/app/agent/nodes/coordinator.py +229 -0
  10. kubeintellect-2.0.0a1/app/agent/nodes/memory_loader.py +31 -0
  11. kubeintellect-2.0.0a1/app/agent/nodes/subagent.py +117 -0
  12. kubeintellect-2.0.0a1/app/agent/state.py +95 -0
  13. kubeintellect-2.0.0a1/app/agent/workflow.py +371 -0
  14. kubeintellect-2.0.0a1/app/api/__init__.py +0 -0
  15. kubeintellect-2.0.0a1/app/api/middleware.py +67 -0
  16. kubeintellect-2.0.0a1/app/api/v1/__init__.py +0 -0
  17. kubeintellect-2.0.0a1/app/api/v1/auth.py +40 -0
  18. kubeintellect-2.0.0a1/app/api/v1/endpoints/__init__.py +0 -0
  19. kubeintellect-2.0.0a1/app/api/v1/endpoints/chat_completions.py +258 -0
  20. kubeintellect-2.0.0a1/app/api/v1/endpoints/events.py +33 -0
  21. kubeintellect-2.0.0a1/app/api/v1/endpoints/health.py +15 -0
  22. kubeintellect-2.0.0a1/app/api/v1/endpoints/namespaces.py +34 -0
  23. kubeintellect-2.0.0a1/app/api/v1/router.py +14 -0
  24. kubeintellect-2.0.0a1/app/cli.py +1752 -0
  25. kubeintellect-2.0.0a1/app/core/__init__.py +0 -0
  26. kubeintellect-2.0.0a1/app/core/config.py +213 -0
  27. kubeintellect-2.0.0a1/app/core/llm.py +101 -0
  28. kubeintellect-2.0.0a1/app/db/__init__.py +0 -0
  29. kubeintellect-2.0.0a1/app/db/audit.py +80 -0
  30. kubeintellect-2.0.0a1/app/db/memory_store.py +181 -0
  31. kubeintellect-2.0.0a1/app/db/schema.sql +72 -0
  32. kubeintellect-2.0.0a1/app/main.py +143 -0
  33. kubeintellect-2.0.0a1/app/streaming/__init__.py +0 -0
  34. kubeintellect-2.0.0a1/app/streaming/emitter.py +176 -0
  35. kubeintellect-2.0.0a1/app/tools/__init__.py +0 -0
  36. kubeintellect-2.0.0a1/app/tools/kubectl_tool.py +388 -0
  37. kubeintellect-2.0.0a1/app/tools/loki_tool.py +195 -0
  38. kubeintellect-2.0.0a1/app/tools/prometheus_tool.py +143 -0
  39. kubeintellect-2.0.0a1/app/tools/registry.py +6 -0
  40. kubeintellect-2.0.0a1/app/utils/__init__.py +0 -0
  41. kubeintellect-2.0.0a1/app/utils/logger.py +115 -0
  42. kubeintellect-2.0.0a1/pyproject.toml +103 -0
@@ -0,0 +1,121 @@
1
+ # KubeIntellect — environment configuration
2
+ #
3
+ # pip install quickstart (no repo clone needed):
4
+ # pip install kubeintellect && pipx install kube-q
5
+ # kubeintellect init ← interactive wizard; writes ~/.kubeintellect/.env
6
+ # kubeintellect serve ← auto-detects database (postgres / docker / sqlite)
7
+ # KUBE_Q_API_KEY=<key> kq --url http://localhost:8000
8
+ #
9
+ # Docker Compose quickstart (from repo):
10
+ # cp .env.example .env
11
+ # # Fill in your LLM API key and POSTGRES_PASSWORD, then:
12
+ # docker compose up -d
13
+ # KUBE_Q_API_KEY=<key> kq
14
+ #
15
+ # See docs/configuration.md for the full variable reference.
16
+
17
+ # ── LLM Provider — choose one: azure | openai ─────────────────────────────────
18
+ LLM_PROVIDER=azure
19
+
20
+ # ── OpenAI (used when LLM_PROVIDER=openai) ────────────────────────────────────
21
+ OPENAI_API_KEY=
22
+ OPENAI_COORDINATOR_MODEL=gpt-4o
23
+ OPENAI_SUBAGENT_MODEL=gpt-4o-mini
24
+
25
+ # ── Azure OpenAI (used when LLM_PROVIDER=azure) ───────────────────────────────
26
+ AZURE_OPENAI_API_KEY=your-azure-api-key
27
+ AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
28
+ AZURE_OPENAI_API_VERSION=2024-08-01-preview
29
+ AZURE_COORDINATOR_DEPLOYMENT=gpt-4o
30
+ AZURE_SUBAGENT_DEPLOYMENT=gpt-4o-mini
31
+
32
+ # ── Database ───────────────────────────────────────────────────────────────────
33
+ # kubeintellect serve auto-detects which backend to use:
34
+ # 1. Postgres running at POSTGRES_HOST:POSTGRES_PORT → uses it
35
+ # 2. Docker available, no postgres → offers to start a container
36
+ # 3. No Docker → falls back to SQLite (disk)
37
+ #
38
+ # Option A: Local postgres (default for Docker Compose / Kind)
39
+ POSTGRES_PASSWORD=changeme
40
+ POSTGRES_HOST=localhost
41
+ POSTGRES_PORT=5432
42
+ POSTGRES_DB=kubeintellect
43
+ POSTGRES_USER=kubeintellect
44
+ POSTGRES_POOL_MIN_CONN=1
45
+ POSTGRES_POOL_MAX_CONN=10
46
+
47
+ # Option B: External / managed database — overrides all POSTGRES_* vars above
48
+ # DATABASE_URL=postgresql://user:password@host:5432/dbname
49
+
50
+ # Option C: SQLite (auto-set by kubeintellect serve; or force it manually)
51
+ # USE_SQLITE=true
52
+ # SQLITE_PATH=~/.kubeintellect/kubeintellect.db
53
+
54
+ # ── Kubernetes ─────────────────────────────────────────────────────────────────
55
+ KUBECONFIG_PATH=~/.kube/config
56
+ KUBECTL_TIMEOUT_SECONDS=30
57
+ KUBECTL_DESTRUCTIVE_TIMEOUT_SECONDS=300
58
+
59
+ # ── Observability — bring your own ────────────────────────────────────────────
60
+ # KubeIntellect queries these to answer metric/log questions about your cluster.
61
+ # Leave empty if you don't have them; kubectl-based queries still work without them.
62
+ #
63
+ # Local (Docker Compose --profile monitoring):
64
+ # PROMETHEUS_URL=http://localhost:9090
65
+ # LOKI_URL=http://localhost:3100
66
+ #
67
+ # Kind cluster (make monitoring-install):
68
+ # PROMETHEUS_URL=http://kube-prometheus-stack-prometheus.monitoring.svc.cluster.local:9090
69
+ # LOKI_URL=http://loki.monitoring.svc.cluster.local:3100
70
+ #
71
+ # Company / remote cluster — set to your existing endpoints:
72
+ PROMETHEUS_URL=
73
+ LOKI_URL=
74
+
75
+ # ── Langfuse — KubeIntellect's internal LLM tracing (optional) ───────────────
76
+ LANGFUSE_ENABLED=false
77
+ LANGFUSE_PUBLIC_KEY=
78
+ LANGFUSE_SECRET_KEY=
79
+ LANGFUSE_HOST=http://localhost:3001
80
+
81
+ # ── Docker Compose profiles ────────────────────────────────────────────────────
82
+ # The docker-compose.yaml defines optional profiles to add observability on top
83
+ # of the core kubeintellect + postgres services.
84
+ #
85
+ # Run with monitoring (Prometheus / Grafana / Loki):
86
+ # docker compose --profile monitoring up -d
87
+ # Then uncomment and set:
88
+ # PROMETHEUS_URL=http://localhost:9090
89
+ # LOKI_URL=http://localhost:3100
90
+ #
91
+ # Run with Langfuse tracing:
92
+ # docker compose --profile tracing up -d
93
+ # Visit http://localhost:3001, create an account, go to Settings → API Keys.
94
+ # Then set LANGFUSE_ENABLED=true and fill in the keys above.
95
+ #
96
+ # Run with both:
97
+ # docker compose --profile monitoring --profile tracing up -d
98
+ #
99
+ # Langfuse docker-compose secrets (only needed when using --profile tracing):
100
+ # LANGFUSE_DB_PASSWORD=langfuse-local
101
+ # LANGFUSE_NEXTAUTH_SECRET=changeme-local-secret-32chars!!
102
+
103
+ # ── Container registry (for kind-build / ghcr pulls) ─────────────────────────
104
+ GHCR_USERNAME=your-github-username
105
+ GHCR_PAT=your-github-pat
106
+
107
+ # ── App ───────────────────────────────────────────────────────────────────────
108
+ # Auth: comma-separated API keys per role. Leave empty to disable auth (open access).
109
+ # admin — high + medium risk ops (delete, drain, apply, scale, exec…), HITL-gated
110
+ # operator — medium risk only (create, apply, scale, exec…), HITL-gated; delete/drain blocked
111
+ # readonly — read-only (get, describe, logs, top, events); all writes rejected
112
+ KUBEINTELLECT_ADMIN_KEYS=
113
+ KUBEINTELLECT_OPERATOR_KEYS=
114
+ KUBEINTELLECT_READONLY_KEYS=
115
+ LOG_LEVEL=INFO
116
+ LOG_FORMAT=text
117
+ DEBUG=false
118
+ ALLOWED_ORIGINS=http://localhost:3080
119
+
120
+ # ── LangChain / LangSmith (optional cloud tracing) ───────────────────────────
121
+ LANGCHAIN_API_KEY=
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.4
2
+ Name: kubeintellect
3
+ Version: 2.0.0a1
4
+ Summary: AI-powered Kubernetes management — local server and CLI
5
+ Project-URL: Homepage, https://github.com/mskazemi/kubeintellect-v2
6
+ Project-URL: Documentation, https://github.com/mskazemi/kubeintellect-v2#readme
7
+ Project-URL: Issues, https://github.com/mskazemi/kubeintellect-v2/issues
8
+ License: MIT
9
+ Keywords: ai,devops,k8s,kubectl,kubernetes,llm
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Intended Audience :: System Administrators
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: System :: Systems Administration
16
+ Requires-Python: >=3.12
17
+ Requires-Dist: asyncpg>=0.29
18
+ Requires-Dist: fastapi>=0.115
19
+ Requires-Dist: httpx>=0.28
20
+ Requires-Dist: kube-q>=1.4
21
+ Requires-Dist: langchain-openai>=0.2
22
+ Requires-Dist: langchain>=0.3
23
+ Requires-Dist: langgraph-checkpoint-postgres>=2.0
24
+ Requires-Dist: langgraph-checkpoint-sqlite>=2.0
25
+ Requires-Dist: langgraph>=0.2
26
+ Requires-Dist: langsmith>=0.2
27
+ Requires-Dist: psycopg[binary,pool]>=3.1
28
+ Requires-Dist: pydantic-settings>=2.6
29
+ Requires-Dist: pydantic>=2.10
30
+ Requires-Dist: python-dotenv>=1.0
31
+ Requires-Dist: pyyaml>=6.0
32
+ Requires-Dist: uvicorn[standard]>=0.32
33
+ Provides-Extra: all
34
+ Requires-Dist: langfuse>=2.0; extra == 'all'
35
+ Requires-Dist: opentelemetry-api>=1.0; extra == 'all'
36
+ Requires-Dist: prometheus-fastapi-instrumentator>=7.1.0; extra == 'all'
37
+ Provides-Extra: metrics
38
+ Requires-Dist: prometheus-fastapi-instrumentator>=7.1.0; extra == 'metrics'
39
+ Provides-Extra: tracing
40
+ Requires-Dist: langfuse>=2.0; extra == 'tracing'
41
+ Requires-Dist: opentelemetry-api>=1.0; extra == 'tracing'
42
+ Description-Content-Type: text/markdown
43
+
44
+ # KubeIntellect V2
45
+
46
+ AI-powered Kubernetes management. Natural-language interface to diagnose faults, query cluster state, and execute remediation — with human approval gating all destructive actions.
47
+
48
+ ---
49
+
50
+ ## Quickstart
51
+
52
+ ### Fastest — pip install (no repo clone needed)
53
+
54
+ ```bash
55
+ pip install kubeintellect
56
+ pipx install kube-q # or: pip install kube-q
57
+
58
+ kubeintellect init # interactive wizard: LLM, database, kubeconfig
59
+ kubeintellect serve # auto-detects database; starts on http://localhost:8000
60
+ ```
61
+
62
+ `kubeintellect serve` handles the database automatically:
63
+ - Postgres running locally → uses it
64
+ - Docker available, no Postgres → offers to start a container
65
+ - No Docker → falls back to SQLite (no extra setup needed)
66
+
67
+ Connect:
68
+ ```bash
69
+ KUBE_Q_API_KEY=<admin-key> kq --url http://localhost:8000
70
+ ```
71
+
72
+ > If `kubeintellect` / `kq` are not found after install, add `~/.local/bin` to PATH:
73
+ > ```bash
74
+ > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
75
+ > ```
76
+
77
+ ---
78
+
79
+ ### Other deployment options
80
+
81
+ | Option | When to use |
82
+ |--------|-------------|
83
+ | [Docker Compose](docs/deploy-docker-compose.md) | Laptop, no K8s cluster, full stack via Docker |
84
+ | [Kind cluster](docs/deploy-kind.md) | Local K8s dev with monitoring + Langfuse |
85
+ | [Cloud / VM (Helm)](docs/deploy-cloud.md) | Production, AKS, or company cluster |
86
+
87
+ Full guide: [docs/quickstart.md](docs/quickstart.md)
88
+
89
+ ---
90
+
91
+ ## Architecture
92
+
93
+ ```
94
+ kq (CLI) ──► KubeIntellect API (FastAPI + LangGraph)
95
+ │
96
+ ├── Coordinator (GPT-4o)
97
+ │ ├── simple query → direct tool use → answer
98
+ │ └── complex fault → fan-out to 4 parallel subagents
99
+ │ ├── Pod subagent (kubectl)
100
+ │ ├── Metrics subagent (Prometheus / PromQL)
101
+ │ ├── Logs subagent (Loki / LogQL)
102
+ │ └── Events subagent (kubectl events)
103
+ │
104
+ ├── HITL gate — destructive ops pause for approval
105
+ └── Role check — admin / operator / readonly enforced
106
+ ```
107
+
108
+ **Checkpointing**: conversation state persists to PostgreSQL (production) or SQLite (local).
109
+
110
+ ---
111
+
112
+ ## Authentication
113
+
114
+ Optional — if no keys are set, all requests are accepted.
115
+
116
+ ```bash
117
+ # ~/.kubeintellect/.env (written by kubeintellect init)
118
+ KUBEINTELLECT_ADMIN_KEYS=ki-admin-abc123
119
+ KUBEINTELLECT_OPERATOR_KEYS=ki-op-def456
120
+ KUBEINTELLECT_READONLY_KEYS=ki-ro-xyz789
121
+ ```
122
+
123
+ Generate keys: `openssl rand -hex 20`
124
+
125
+ ---
126
+
127
+ ## Repo layout
128
+
129
+ ```
130
+ app/ # core Python source (shared by all deployments)
131
+ deploy/
132
+ docker-compose/ # monitoring configs (prometheus.yml, loki-config.yml, grafana)
133
+ helm/
134
+ kubeintellect/ # Helm chart + values for all environments
135
+ langfuse/ # Langfuse LLM tracing chart
136
+ kind/ # Kind cluster configs
137
+ docker-compose.yaml # laptop deployment entry point
138
+ scripts/
139
+ kind/create-kind-cluster.sh
140
+ vm/setup-nginx.sh, setup-tls.sh
141
+ tests/
142
+ docs/
143
+ ```
144
+
145
+ ---
146
+
147
+ ## `kubeintellect kind-setup` vs `make kind-cluster-create`
148
+
149
+ Two ways to get a local Kind cluster — pick based on who you are:
150
+
151
+ | | `kubeintellect kind-setup` | `make kind-cluster-create` |
152
+ |---|---|---|
153
+ | Requires repo clone | No | Yes |
154
+ | Cluster config | Single-node | 2-node, hot-reload mounts |
155
+ | Ingress | Basic nginx | Tuned for Kind dev |
156
+ | Cluster DNS auto-config | Yes — `svc.cluster.local` works from host | No |
157
+ | Monitoring / Langfuse | Via `make` targets (after cloning) | `make monitoring-install` / `make langfuse-install` |
158
+ | Who it's for | End users, ops teams | KubeIntellect developers |
159
+
160
+ ---
161
+
162
+ ## Docs
163
+
164
+ | Topic | File |
165
+ |---|---|
166
+ | All install options | [docs/quickstart.md](docs/quickstart.md) |
167
+ | pip — no cluster (quick try) | [docs/install-pip-no-cluster.md](docs/install-pip-no-cluster.md) |
168
+ | pip — existing cluster | [docs/install-pip-existing-cluster.md](docs/install-pip-existing-cluster.md) |
169
+ | pip — local Kind cluster | [docs/install-pip-kind.md](docs/install-pip-kind.md) |
170
+ | Docker Compose | [docs/deploy-docker-compose.md](docs/deploy-docker-compose.md) |
171
+ | Kind dev environment (repo) | [docs/deploy-kind.md](docs/deploy-kind.md) |
172
+ | VM / AKS / cloud (Helm) | [docs/deploy-cloud.md](docs/deploy-cloud.md) |
173
+ | All config options | [docs/configuration.md](docs/configuration.md) |
@@ -0,0 +1,130 @@
1
+ # KubeIntellect V2
2
+
3
+ AI-powered Kubernetes management. Natural-language interface to diagnose faults, query cluster state, and execute remediation — with human approval gating all destructive actions.
4
+
5
+ ---
6
+
7
+ ## Quickstart
8
+
9
+ ### Fastest — pip install (no repo clone needed)
10
+
11
+ ```bash
12
+ pip install kubeintellect
13
+ pipx install kube-q # or: pip install kube-q
14
+
15
+ kubeintellect init # interactive wizard: LLM, database, kubeconfig
16
+ kubeintellect serve # auto-detects database; starts on http://localhost:8000
17
+ ```
18
+
19
+ `kubeintellect serve` handles the database automatically:
20
+ - Postgres running locally → uses it
21
+ - Docker available, no Postgres → offers to start a container
22
+ - No Docker → falls back to SQLite (no extra setup needed)
23
+
24
+ Connect:
25
+ ```bash
26
+ KUBE_Q_API_KEY=<admin-key> kq --url http://localhost:8000
27
+ ```
28
+
29
+ > If `kubeintellect` / `kq` are not found after install, add `~/.local/bin` to PATH:
30
+ > ```bash
31
+ > echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
32
+ > ```
33
+
34
+ ---
35
+
36
+ ### Other deployment options
37
+
38
+ | Option | When to use |
39
+ |--------|-------------|
40
+ | [Docker Compose](docs/deploy-docker-compose.md) | Laptop, no K8s cluster, full stack via Docker |
41
+ | [Kind cluster](docs/deploy-kind.md) | Local K8s dev with monitoring + Langfuse |
42
+ | [Cloud / VM (Helm)](docs/deploy-cloud.md) | Production, AKS, or company cluster |
43
+
44
+ Full guide: [docs/quickstart.md](docs/quickstart.md)
45
+
46
+ ---
47
+
48
+ ## Architecture
49
+
50
+ ```
51
+ kq (CLI) ──► KubeIntellect API (FastAPI + LangGraph)
52
+ │
53
+ ├── Coordinator (GPT-4o)
54
+ │ ├── simple query → direct tool use → answer
55
+ │ └── complex fault → fan-out to 4 parallel subagents
56
+ │ ├── Pod subagent (kubectl)
57
+ │ ├── Metrics subagent (Prometheus / PromQL)
58
+ │ ├── Logs subagent (Loki / LogQL)
59
+ │ └── Events subagent (kubectl events)
60
+ │
61
+ ├── HITL gate — destructive ops pause for approval
62
+ └── Role check — admin / operator / readonly enforced
63
+ ```
64
+
65
+ **Checkpointing**: conversation state persists to PostgreSQL (production) or SQLite (local).
66
+
67
+ ---
68
+
69
+ ## Authentication
70
+
71
+ Optional — if no keys are set, all requests are accepted.
72
+
73
+ ```bash
74
+ # ~/.kubeintellect/.env (written by kubeintellect init)
75
+ KUBEINTELLECT_ADMIN_KEYS=ki-admin-abc123
76
+ KUBEINTELLECT_OPERATOR_KEYS=ki-op-def456
77
+ KUBEINTELLECT_READONLY_KEYS=ki-ro-xyz789
78
+ ```
79
+
80
+ Generate keys: `openssl rand -hex 20`
81
+
82
+ ---
83
+
84
+ ## Repo layout
85
+
86
+ ```
87
+ app/ # core Python source (shared by all deployments)
88
+ deploy/
89
+ docker-compose/ # monitoring configs (prometheus.yml, loki-config.yml, grafana)
90
+ helm/
91
+ kubeintellect/ # Helm chart + values for all environments
92
+ langfuse/ # Langfuse LLM tracing chart
93
+ kind/ # Kind cluster configs
94
+ docker-compose.yaml # laptop deployment entry point
95
+ scripts/
96
+ kind/create-kind-cluster.sh
97
+ vm/setup-nginx.sh, setup-tls.sh
98
+ tests/
99
+ docs/
100
+ ```
101
+
102
+ ---
103
+
104
+ ## `kubeintellect kind-setup` vs `make kind-cluster-create`
105
+
106
+ Two ways to get a local Kind cluster — pick based on who you are:
107
+
108
+ | | `kubeintellect kind-setup` | `make kind-cluster-create` |
109
+ |---|---|---|
110
+ | Requires repo clone | No | Yes |
111
+ | Cluster config | Single-node | 2-node, hot-reload mounts |
112
+ | Ingress | Basic nginx | Tuned for Kind dev |
113
+ | Cluster DNS auto-config | Yes — `svc.cluster.local` works from host | No |
114
+ | Monitoring / Langfuse | Via `make` targets (after cloning) | `make monitoring-install` / `make langfuse-install` |
115
+ | Who it's for | End users, ops teams | KubeIntellect developers |
116
+
117
+ ---
118
+
119
+ ## Docs
120
+
121
+ | Topic | File |
122
+ |---|---|
123
+ | All install options | [docs/quickstart.md](docs/quickstart.md) |
124
+ | pip — no cluster (quick try) | [docs/install-pip-no-cluster.md](docs/install-pip-no-cluster.md) |
125
+ | pip — existing cluster | [docs/install-pip-existing-cluster.md](docs/install-pip-existing-cluster.md) |
126
+ | pip — local Kind cluster | [docs/install-pip-kind.md](docs/install-pip-kind.md) |
127
+ | Docker Compose | [docs/deploy-docker-compose.md](docs/deploy-docker-compose.md) |
128
+ | Kind dev environment (repo) | [docs/deploy-kind.md](docs/deploy-kind.md) |
129
+ | VM / AKS / cloud (Helm) | [docs/deploy-cloud.md](docs/deploy-cloud.md) |
130
+ | All config options | [docs/configuration.md](docs/configuration.md) |
File without changes
@@ -0,0 +1,3 @@
1
+ from app.cli import main
2
+
3
+ main()
File without changes
@@ -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
+ }