iflow-mcp_ayushpani_mcp-k8s 0.1.0
Add your description here
Requires Python: >=3.10

# KS-AI: AI-Powered Kubernetes Operations Assistant

[![Go](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org)
[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python)](https://python.org)
[![Gemini](https://img.shields.io/badge/Gemini-AI-4285F4?style=flat&logo=google)](https://ai.google.dev)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**KS-AI** is a production-grade AI assistant that brings natural language understanding to Kubernetes operations. Ask questions in plain English, get intelligent responses with real-time cluster insights.

---

## Why KS-AI?

| Traditional K8s Management | With KS-AI |
|---------------------------|------------|
| `kubectl get pods -n app -o wide \| grep -v Running` | "Show me unhealthy pods in the app namespace" |
| Multiple commands + manual analysis | Single natural language query |
| Requires memorizing kubectl syntax | Just describe what you need |
| No context awareness | Understands your cluster state |

### Key Differentiators

- **Natural Language Interface** - No more memorizing kubectl flags and YAML syntax
- **Real-time Cluster Awareness** - AI queries your actual cluster, not just documentation
- **Production-Safe** - Built-in guardrails prevent destructive operations without confirmation
- **Multi-Model Fallback** - Automatic failover between Gemini models on rate limits
- **Beautiful TUI** - Full-featured terminal interface with animations

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         KS-AI System                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
│  │   Go TUI    │───▶│   FastAPI   │───▶│   MCP Server        │ │
│  │  (ks-ai)    │    │   Backend   │    │  (K8s Tools)        │ │
│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
│        │                  │                      │              │
│        │                  ▼                      ▼              │
│        │           ┌─────────────┐    ┌─────────────────────┐  │
│        │           │  Gemini AI  │    │  Kubernetes API     │  │
│        │           │  (+ Fallback│    │  (kubectl/client)   │  │
│        │           │   Models)   │    └─────────────────────┘  │
│        │           └─────────────┘                              │
│        │                                                        │
│        └─────────── Server-Sent Events (SSE) ◀──────────────────│
│                     (Real-time Streaming)                       │
└─────────────────────────────────────────────────────────────────┘
```

---

## Features

### 1. Intelligent Terminal UI (TUI)

Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea), the TUI provides:

- **Split-Pane View** - Chat on left, command logs on right
- **Resizable Panes** - `Ctrl+←/→` to adjust widths
- **Mouse Support** - Scroll with mouse wheel, click to focus
- **Keyboard Navigation** - Full vim-style and arrow key support
- **Real-time Streaming** - Watch AI responses appear character by character
- **Syntax Highlighting** - kubectl commands are color-coded
- **Animated Elements** - Walking cat 🐱, loading spinner

### 2. MCP Server (Model Context Protocol)

Exposes Kubernetes operations as AI-callable tools:

| Tool | Description |
|------|-------------|
| `list_namespaces` | Get all namespaces |
| `list_pods` | List pods with status, restarts, age |
| `list_deployments` | Deployment details and replica status |
| `list_services` | Service types, ports, selectors |
| `get_pod_logs` | Retrieve container logs |
| `describe_resource` | Detailed resource information |
| `apply_manifest` | Apply YAML configurations |
| `delete_resource` | Remove resources (with confirmation) |
| `scale_deployment` | Adjust replica counts |
| `get_cluster_info` | Cluster version and health |

### 3. Resilient AI Backend

- **Multi-Model Fallback** - Cycles through models on rate limits:
  ```
  gemini-2.5-pro → gemini-2.0-flash → gemini-2.0-flash-lite → gemini-1.5-flash
  ```
- **Automatic Retry** - Exponential backoff with smart delay parsing
- **Rate Limiting** - 500ms minimum between API calls
- **Conversation History** - Maintains context (last 20 messages)

### 4. Production Safety

- **Destructive Operation Warnings** - Delete/scale operations require confirmation
- **Namespace Isolation** - Operations scoped to current namespace by default
- **Audit Logging** - All kubectl commands logged to file
- **Error Recovery** - Graceful handling of cluster connectivity issues

---

## Quick Start

### Prerequisites

- **Go 1.21+** - For TUI binary
- **Python 3.10+** - For backend and MCP server
- **kubectl** - Configured with cluster access
- **Gemini API Key** - From [Google AI Studio](https://aistudio.google.com/apikey)

### Installation

```bash
# Clone repository
git clone https://github.com/Ayushpani/ks-ai.git
cd ks-ai

# Set up Python environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure API key
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

# Build TUI
cd cmd/ks-ai && go build -o ../../ks-ai && cd ../..
```

### Running

```bash
# Terminal 1: Start MCP Server
make mcp-server

# Terminal 2: Start Backend  
make backend

# Terminal 3: Launch TUI
./ks-ai
```

Or use the combined command:
```bash
make dev  # Starts all services
```

---

## Usage Examples

### Basic Queries

```
> List all pods in default namespace
> Show me deployments that are not fully available
> What services are exposed externally?
> Get logs from the nginx pod
```

### Troubleshooting

```
> Why is my pod crashing?
> Show pods with high restart counts
> What's consuming the most memory?
> Are there any pending pods?
```

### Operations

```
> Scale the web deployment to 5 replicas
> Describe the redis service
> Get events from the api namespace
> Show me the YAML for deployment/app
```

---

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Enter` | Send message |
| `Tab` | Switch between Chat/Log panes |
| `↑/↓` | Scroll content |
| `Ctrl+U/D` | Page up/down |
| `Ctrl+←/→` | Resize panes |
| `Ctrl+Y` | Copy chat to clipboard |
| `Ctrl+L` | Clear conversation history |
| `F1` | Toggle help menu |
| `Ctrl+C` | Exit |

---

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GOOGLE_API_KEY` | Gemini API key | Required |
| `GEMINI_MODEL` | Primary model | `gemini-2.5-flash` |
| `MCP_SERVER_URL` | MCP server endpoint | `http://localhost:8000/sse` |
| `BACKEND_PORT` | Backend API port | `8080` |

### Fallback Models

Edit `app/backend/app/services/gemini_service.py`:

```python
FALLBACK_MODELS = [
    'gemini-2.5-pro',
    'gemini-2.0-flash',
    'gemini-2.0-flash-lite',
    'gemini-1.5-flash',
]
```

---

## Project Structure

```
ks-ai/
├── cmd/ks-ai/           # Go TUI application
│   └── main.go          # TUI entry point
├── internal/tui/        # TUI components
│   ├── mcp_client.go    # Backend API client
│   └── markdown.go      # Markdown rendering
├── app/
│   ├── backend/         # FastAPI backend
│   │   └── app/
│   │       ├── api/     # REST endpoints
│   │       └── services/# Gemini, Chat services
│   └── frontend/        # React web UI (optional)
├── k8s_mcp_server.py    # MCP server with K8s tools
├── mcp_client.py        # Python MCP client
└── Makefile             # Build commands
```

---

## Why This Matters

### For Developers
- **Faster debugging** - Get instant insights without constructing complex queries
- **Lower barrier** - New team members can operate clusters immediately
- **Context retention** - AI remembers your conversation for follow-ups

### For SREs/DevOps
- **Incident response** - Quickly assess cluster state during outages
- **Audit trail** - All commands logged for compliance
- **Safety guardrails** - Prevent accidental damage

### For Teams
- **Knowledge democratization** - Not everyone needs to be a kubectl expert
- **Consistent operations** - AI follows best practices
- **Documentation on demand** - Ask "why" and get explanations

---

## Contributing

Contributions welcome! Areas of interest:

- Additional K8s tools (CRDs, Helm, etc.)
- Support for other AI providers (Claude, OpenAI)
- Web UI improvements
- Multi-cluster support

---

## License

MIT License - See [LICENSE](LICENSE) for details.

---

## Acknowledgments

- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework
- [Google Gemini](https://ai.google.dev) - AI models
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP implementation
- [Kubernetes Python Client](https://github.com/kubernetes-client/python)

---

**Built with ❤️ for the Kubernetes community**