Metadata-Version: 2.4
Name: super-power-bedrock
Version: 0.4.2
Summary: A Bedrock-backed AWS and Kubernetes operations assistant
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3<2,>=1.34
Requires-Dist: botocore<2,>=1.34
Requires-Dist: rich<15,>=13
Provides-Extra: kubernetes
Requires-Dist: kubernetes<34,>=28; extra == "kubernetes"
Provides-Extra: ui
Requires-Dist: prompt-toolkit<4,>=3; extra == "ui"
Dynamic: license-file

# Super Power

Super Power is a conversational AWS and Kubernetes operations assistant that
uses the Amazon Bedrock Converse API. It can inspect resources, investigate
metrics and logs, and perform guarded operations after explicit approval.

## How to run

```bash
python -m pip install super-power-bedrock
super-power
```

Ask a one-off question:

```bash
super-power "List EKS clusters in us-west-2"
```

Or start an interactive session:

```bash
super-power --interactive
```

Check this machine's AWS identity, Bedrock model access, and Kubernetes client
readiness before starting work:

```bash
super-power --preflight
```

Interactive sessions run this credential-safe check at startup. Use
`--skip-preflight` only when you deliberately want to suppress its display;
it does not disable runtime safety checks. Within an interactive session, run
`/doctor` to repeat the check.

Choose a model or AWS Region when needed:

```bash
super-power --model <model-or-profile-id> --region eu-west-1 "Show EC2 instances"
```

## Requirements

- Python 3.9 or later
- AWS credentials supplied by a standard AWS profile, IAM Identity Center,
  environment variables, an EC2 instance profile, or an EKS web-identity role
- Amazon Bedrock model access and `bedrock:InvokeModel` permission for the
  selected model and Region

Install Kubernetes support when you need Kubernetes API tools:

```bash
python -m pip install "super-power[kubernetes]"
```

## Safety

Read-only operations run without confirmation. Operations that create, change,
restart, scale, delete, or send commands require approval. A built-in block
list refuses destructive commands even when approval is supplied.

The tool does not create AWS credentials, enable Bedrock model access, or
change account-level permissions. Never put credentials, access keys, or
tokens into source code, memory files, or package configuration.

If Bedrock invocation is denied, preflight identifies the active AWS role,
account, model or inference profile, and Region, then explains the smallest
safe administrator checks. It never prints credential values. The readiness
probe sends a fixed one-token request without conversation history solely to
verify the selected model's Converse permission.

## Troubleshooting documentation

For AWS and Kubernetes investigations, Super Power can retrieve concise,
cited guidance from official AWS and Kubernetes documentation. It only contacts
allowlisted HTTPS documentation domains, uses bounded response sizes and
timeouts, and never sends credentials or cookies. If documentation is
unavailable, it reports the official source link rather than inventing advice.

Interactive terminals use a color-aware Rich interface with a thinking/progress
indicator. Set `NO_COLOR=1` or redirect output for plain text;
`--json` always emits machine-readable JSON only.

The interface uses a warm-coral `#D97757` accent for the original Super Power
lightning mark, section headings, table headers, borders, prompts, and status
indicator. Green, amber, red, and dim text are reserved for semantic success,
approval/warning, errors, and secondary information. Color is optional: plain
text and JSON remain complete and readable.

Normal interactive use shows only a generic thinking indicator. Pass
`--verbose` when you need sanitized tool names and activity diagnostics.
Routine intermediate tool failures are kept out of the normal UI; the final
answer explains only relevant evidence. Approval prompts show the requested
action or command, rather than internal tool JSON.

The terminal UI uses no emoji and falls back to plain text when output is
redirected or `NO_COLOR` is set. It deliberately uses the lightweight standard
input path, avoiding raw-terminal dependencies that can degrade performance in
minimal EC2 and container environments.

Use `/help` in an interactive session for `/status`, `/details`, `/theme`,
`/doctor`, `/clear`, and `/exit`. Prefix an existing allowlisted local
diagnostic with `!`, for example `! df -h`; this is not a general shell escape.

For in-process history, slash-command completion, and keyboard navigation,
install the optional UI extra. It is lazy-loaded and the normal input path is
used automatically when the extra or a compatible terminal is unavailable.

```bash
python -m pip install "super-power-bedrock[ui]"
```

## Audit log and fresh sessions

Super Power stores a sanitized append-only audit log named `super_power.log`
in the directory where it is started. It records compact requests, outcomes,
and tool status, but it is never sent to Bedrock as conversation history.

On the first `0.3.4` run, an existing `ai_memory.dm` is renamed to a dated
`ai_memory.dm.archived-...` backup. This stops old conversations from causing
the model to resume a previous investigation. `/clear` clears only the current
in-process session; the audit log remains intact.

## SES email identities

Super Power can create an Amazon SES email identity after explicit approval.
That action asks AWS to send its verification email; it does not and cannot
bypass the mailbox verification link. Ask the assistant to check the identity
status after the link is used, then send email with a verified `from_email` or
the `EMAIL_FROM` environment variable. Datadog is not part of this package.

## EKS workload access

Super Power runs safe diagnostics directly on the host where it is started.
It uses SSM only for an explicitly selected different managed instance. To
inspect Kubernetes namespaces, pods, events, logs, and deployments, install
the Kubernetes extra and allow the agent to create/update local kubeconfig for
the chosen EKS cluster. This connects through the Kubernetes API; it does not
open an interactive SSH, SSM, or pod-exec session.

Raw `kubectl` and raw `aws eks update-kubeconfig` commands are blocked by the
deterministic JEV guard. After approved EKS connection, the agent uses typed
Kubernetes API tools for Services, Ingresses, and Istio/Gateway API routing
resources instead.

Generic AWS SDK reads are also constrained to a bundled JEV capability catalog.
Before an AWS request, Super Power validates the selected service, operation,
and input parameters against the installed botocore service model. Unsupported
operations and missing required parameters are rejected locally; every allowed
catalog operation includes an official AWS Boto3 reference URL in its
structured result.

## Capacity and quota assessments

Capacity and quota requests use a narrow, deterministic investigation plan.
Super Power calculates EC2 vCPU and memory from `DescribeInstanceTypes`, reads
the account's actual EC2 on-demand standard-vCPU quota from Service Quotas,
and reads applied EKS quotas. After an approved EKS connection it calculates
Kubernetes allocatable CPU, memory, pod slots, node conditions, and resource
limit coverage through the typed Kubernetes API.

It does not guess AWS quota defaults or infer capacity from instance-type
names. If a quota, Kubernetes connection, or live Metrics Server data is not
available, the response labels it unavailable. Normal output is limited to
verified failures, measured utilization at or above 80%, and unavailable data.

## EBS volumes

Super Power can list EBS volumes with size, type, encryption, attachment, and
attachment-time evidence. For a request such as “last usage,” it checks the
most recent observed `VolumeReadOps` or `VolumeWriteOps` CloudWatch data in a
bounded lookback period. This is reported as recent observed I/O, not as a
permanent “last used” timestamp, because EBS does not provide one.

## License

Apache-2.0. See [LICENSE](LICENSE).
