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.
- kubeintellect-2.0.0a1/.env.example +121 -0
- kubeintellect-2.0.0a1/PKG-INFO +173 -0
- kubeintellect-2.0.0a1/README.md +130 -0
- kubeintellect-2.0.0a1/app/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/__main__.py +3 -0
- kubeintellect-2.0.0a1/app/agent/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/agent/hitl.py +21 -0
- kubeintellect-2.0.0a1/app/agent/nodes/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/agent/nodes/coordinator.py +229 -0
- kubeintellect-2.0.0a1/app/agent/nodes/memory_loader.py +31 -0
- kubeintellect-2.0.0a1/app/agent/nodes/subagent.py +117 -0
- kubeintellect-2.0.0a1/app/agent/state.py +95 -0
- kubeintellect-2.0.0a1/app/agent/workflow.py +371 -0
- kubeintellect-2.0.0a1/app/api/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/api/middleware.py +67 -0
- kubeintellect-2.0.0a1/app/api/v1/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/api/v1/auth.py +40 -0
- kubeintellect-2.0.0a1/app/api/v1/endpoints/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/api/v1/endpoints/chat_completions.py +258 -0
- kubeintellect-2.0.0a1/app/api/v1/endpoints/events.py +33 -0
- kubeintellect-2.0.0a1/app/api/v1/endpoints/health.py +15 -0
- kubeintellect-2.0.0a1/app/api/v1/endpoints/namespaces.py +34 -0
- kubeintellect-2.0.0a1/app/api/v1/router.py +14 -0
- kubeintellect-2.0.0a1/app/cli.py +1752 -0
- kubeintellect-2.0.0a1/app/core/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/core/config.py +213 -0
- kubeintellect-2.0.0a1/app/core/llm.py +101 -0
- kubeintellect-2.0.0a1/app/db/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/db/audit.py +80 -0
- kubeintellect-2.0.0a1/app/db/memory_store.py +181 -0
- kubeintellect-2.0.0a1/app/db/schema.sql +72 -0
- kubeintellect-2.0.0a1/app/main.py +143 -0
- kubeintellect-2.0.0a1/app/streaming/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/streaming/emitter.py +176 -0
- kubeintellect-2.0.0a1/app/tools/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/tools/kubectl_tool.py +388 -0
- kubeintellect-2.0.0a1/app/tools/loki_tool.py +195 -0
- kubeintellect-2.0.0a1/app/tools/prometheus_tool.py +143 -0
- kubeintellect-2.0.0a1/app/tools/registry.py +6 -0
- kubeintellect-2.0.0a1/app/utils/__init__.py +0 -0
- kubeintellect-2.0.0a1/app/utils/logger.py +115 -0
- 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
|
|
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
|
+
}
|