Metadata-Version: 2.4
Name: k8agent
Version: 0.1.0
Summary: A read-only Kubernetes natural-language CLI agent using LangGraph
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: langgraph>=0.0.30
Requires-Dist: langchain-core>=0.1.30
Requires-Dist: langchain-openai>=0.1.0
Requires-Dist: kubernetes>=29.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"

# k8agent — Kubernetes Natural-Language Agent (MVP)

`k8agent` is a read-only, session-safe CLI tool designed to help you interactively diagnose and query your Kubernetes clusters in natural language. It uses a LangGraph ReAct agent and LangChain to interface with Kubernetes clusters.

## Features

- **Secure Session-Only Credentials:** LLM keys and configurations are held strictly in memory.
- **Strict Read-Only Access:** Never modifies cluster state (no delete, apply, patch, scale, etc.).
- **Namespace Allowed List:** Restricts the LLM agent to a user-approved set of namespaces.
- **Evidence-Gathering Agent:** Calls tools in sequence (e.g. list pods -> check logs) before coming to a conclusion.

---

## 1. Quick Start

### Prerequisites
- Python 3.11+
- A working Kubernetes context configured in `~/.kube/config`

### Installation
Clone the repository and install the dependencies:
```bash
# Initialize a virtual environment
python -m venv .venv
.\.venv\Scripts\activate

# Install the package in editable mode
pip install -e .[dev]
```

### Starting the REPL
```bash
k8agent
# Or alternatively
python -m k8agent.cli
```

---

## 2. Configuring RBAC (Recommended Security Boundary)

To restrict the agent to read-only actions and specific namespaces, apply the provided template.

1. **Customize the template:**
   Open `k8s/rbac-template.yaml` and replace `{{NAMESPACE}}` with the namespace you wish to grant access to (e.g. `default`).
   
2. **Apply the template:**
   ```bash
   kubectl apply -f k8s/rbac-template.yaml
   ```

3. **Generate Kubeconfig for the ServiceAccount:**
   Use the following commands to create a temporary token and generate a dedicated kubeconfig context pointing to this ServiceAccount:
   ```bash
   # Create a token for the ServiceAccount
   kubectl create token k8agent-sa --namespace=<YOUR_NAMESPACE>
   ```
   You can then configure this token in a separate kubeconfig file to guarantee the cluster-side RBAC boundary.

---

## 3. Tool Reference

The agent has access to the following explicit list of tools:
- `list_allowed_namespaces`: Get the namespace scope of the current session.
- `list_pods`: Get names, status, and restart counts.
- `describe_pod`: Get detailed container statuses and conditions.
- `get_pod_logs`: Retrieve container logs (supports `tail_lines` and `previous`).
- `list_deployments`: View desired vs ready replicas.
- `describe_deployment`: View rolling status and conditions.
- `list_services`: View type, cluster IP, and ports.
- `list_events`: View recent events sorted by last-seen.
- `list_configmaps`: View names and keys only.
- `get_node_status`: View node names and cluster resource conditions (cluster-scoped).

---

## 4. Running Tests

To run unit tests against a mocked Kubernetes API:
```bash
pytest tests/
```

---

## 5. Publishing to PyPI

To build and upload the package to PyPI so it can be installed globally via `pip`:

1. **Install build tools:**
   ```bash
   pip install build twine
   ```

2. **Build the source and binary wheels:**
   ```bash
   python -m build
   ```
   *This generates `.tar.gz` and `.whl` files in the `dist/` directory.*

3. **Upload to PyPI:**
   ```bash
   python -m twine upload dist/*
   ```

