Metadata-Version: 2.4
Name: propt
Version: 0.1.1
Summary: Pre-action operational intelligence layer for infrastructure changes.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: kubernetes>=29.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0

# propt

Pre-action operational intelligence for Kubernetes. `propt` wraps `kubectl`
transparently — mutating commands (delete, scale, apply, patch, edit,
replace, rollout) get a real, live-cluster impact check and a
`Execute? [y/N]` prompt first. Read-only commands pass straight through
with zero overhead.

Built on real open-source signals, not a hardcoded risk table:
- **kubernetes** Python client — live resource discovery
- **networkx** — dependency graph from real `ownerReferences` and
  label-selector matching (no invented relationships)
- **Popeye** (derailed/popeye) — real, actively-maintained cluster
  sanitizer, used as the operational risk knowledge source
- **metrics-server** (optional) — real CPU usage, if installed

Every decision is also logged as an auditable record to **Amazon S3**
via `boto3` — see [AWS integration](#aws-integration-audit-logging) below.

---

## 1. Install (Windows 11 / PowerShell)

### Python dependencies
```powershell
cd propt
pip install -e .
pip install pytest
```

### Popeye (Windows binary, no Go toolchain needed)
1. Go to https://github.com/derailed/popeye/releases
2. Download the latest `popeye_Windows_x86_64.tar.gz` (or `.zip` if offered)
3. Extract `popeye.exe` somewhere on your PATH, e.g. `C:\tools\popeye.exe`
4. Verify: `popeye version`

If Popeye isn't found on PATH, `propt` still works — it just reports
"popeye not available" in the Unknown/missing context section instead
of fabricating findings.

### Cluster
Make sure `kubectl` points at your minikube cluster:
```powershell
minikube status
kubectl get nodes
```

### metrics-server (optional, for real load data)
```powershell
minikube addons enable metrics-server
```

### AWS (for audit logging)
`propt` writes every decision it makes to an S3 bucket as a timestamped
JSON record, using your existing AWS CLI credentials (via `boto3` —
no keys are stored or handled by propt itself).

```powershell
aws configure          # if not already set up
aws s3 mb s3://<your-bucket-name> --region ap-south-1
```
Set the bucket name propt should use (defaults to `propt-audit-logs-sid-2026`
if unset):
```powershell
$env:PROPT_AUDIT_BUCKET = "<your-bucket-name>"
```
If AWS isn't configured, `propt` still works — audit logging fails
silently rather than blocking the actual kubectl operation.

---

## 2. Verify it's wired up
```powershell
pytest
```
These tests mock the cluster so they run without one — they document
expected behavior (see `tests/test_engine.py`). The real proof is the
live demo below.

---

## 3. Set up the demo scenario

Deploy two contrasting workloads into your cluster:

```powershell
kubectl create deployment payment-api --image=nginx --replicas=3
kubectl create deployment worker --image=nginx --replicas=10
kubectl expose deployment payment-api --port=80 --name=payment-api

# Simulate the understaffed condition
kubectl scale deployment payment-api --replicas=3
kubectl delete pod <one-of-the-payment-api-pods>   # bring it to 2/3 without propt, to set the stage
```

(Or just let `propt` itself do the second delete below — the first
manual delete above is only to establish the "already short one
replica" starting condition for the demo.)

## 4. Run it

```powershell
propt kubectl delete pod <another-payment-api-pod-name>
```
Expect: **HIGH POTENTIAL IMPACT** — evidence should show available
replicas below desired, plus any live Popeye findings for that
deployment.

```powershell
propt kubectl delete pod <a-worker-pod-name>
```
Expect: **NONE / low impact** — same engine, different live state,
different conclusion.

```powershell
propt kubectl get pods
```
Expect: passes straight through immediately, no analysis, no prompt.

---

## Architecture

```
kubectl command
      |
      v
Common Change Model (propt/parser.py)
      |
      v
Live Resource Graph (propt/k8s_graph.py) --- built from real ownerReferences + selectors
      |
      v
Impact Inference Engine (propt/engine.py) --- combines graph + Popeye findings + metrics
      |
      v
Explanation (propt/explain.py) --- printed to terminal, evidence-based, no opaque score
      |
      v
Execute? [y/N] --- human decides
      |
      +---> Audit record written to Amazon S3 (propt/audit.py, via boto3)
      |
      v
propt runs the ORIGINAL kubectl command as-is
```


## AWS integration: audit logging

Every impact decision — the command, the target, the evidence, the
consequence text, and whether the engineer chose to proceed — is
written to Amazon S3 as a timestamped JSON object under
`decisions/<timestamp>.json`. This gives a team a real, queryable
history of infrastructure decisions and their reasoning, matching the
"auditable, trust-first" principle from the original project spec
(never silently change policy; keep evidence and outcomes reviewable).

Example record:
```json
{
  "timestamp": "2026-09-20T06:48:43.005997+00:00",
  "command": "delete pod payment-api-85648675fb-6bj46",
  "target": "pod/payment-api-85648675fb-6bj46",
  "impact_level": "HIGH",
  "evidence": ["deployment/payment-api: available replicas (5) below desired (6)"],
  "consequence": "Potential reduction in capacity or degraded state propagating to: deployment/payment-api, replicaset/payment-api-85648675fb, service/payment-api.",
  "executed": false
}
```

Audit logging is intentionally fire-and-forget: if AWS credentials
aren't configured or S3 is unreachable, `propt` degrades silently and
the actual kubectl workflow is never blocked.

## What this is not (by design, for the hackathon scope)
- Not tied to a hardcoded command→risk table — risk comes from live
  cluster state + Popeye's real findings.
- Not a live "traffic" simulator — if metrics-server isn't installed,
  it says so rather than inventing a number.
- No LLM reasoning layer, no multi-provider adapters (Terraform etc.),
  no auth/security hardening — explicitly out of scope for this build,
  same as the original project spec.
