mtv-agent 0.1.0__tar.gz

mtv_agent-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# VSCode files
+.vscode/
+
+# Virtual environments
+.venv
+
+# Ruff cache
+.ruff_cache/
+
+# Config (may contain API keys or tokens)
+config.json
+
+# Web UI
+web/node_modules/
+web/dist/
+web/bun.lock
+
+# Bundled web dist (build artifact for pip package)
+mtv_agent/web_dist/
+
+.cache/

mtv_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

mtv_agent-0.1.0/Makefile

@@ -0,0 +1,69 @@
+.DEFAULT_GOAL := help
+.PHONY: run run-cop dev serve build-web dev-web stop format format-web lint lint-web package help
+
+## Run the full stack via scripts/run.sh (dev)
+run:
+	@scripts/run.sh
+
+## Run with COP via scripts/run.sh (dev)
+run-cop:
+	@scripts/run.sh --with-cop
+
+## Run API server with --no-web for frontend dev
+dev:
+	@NO_WEB=1 scripts/run.sh
+
+## Start only the API server (pip-installed entrypoint)
+serve:
+	CONFIG=./config.json uv run python -m mtv_agent serve
+
+## Build the web UI into web/dist
+build-web:
+	cd web && npm ci && npm run build
+
+## Start the Vite dev server for the web UI
+dev-web:
+	cd web && npm run dev
+
+## Stop all MCP containers and proxy
+stop:
+	@echo "Stopping MCP containers..."
+	@docker stop mtv-agent-mcp-mtv 2>/dev/null || podman stop mtv-agent-mcp-mtv 2>/dev/null || true
+	@docker stop mtv-agent-mcp-metrics 2>/dev/null || podman stop mtv-agent-mcp-metrics 2>/dev/null || true
+	@docker stop mtv-agent-mcp-debug-queries 2>/dev/null || podman stop mtv-agent-mcp-debug-queries 2>/dev/null || true
+	@echo "Stopping claude-openai-proxy (if running)..."
+	@pkill -f 'claude_openai_proxy' 2>/dev/null || true
+	@echo "Done."
+
+## Format Python code with ruff
+format:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+## Format web code with prettier
+format-web:
+	cd web && npm run format
+
+## Lint Python code with ruff
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+
+## Lint web code with eslint and prettier
+lint-web:
+	cd web && npm run lint && npm run format:check
+
+## Build pip-distributable package (includes web UI)
+package: build-web
+	rm -rf mtv_agent/web_dist
+	cp -r web/dist mtv_agent/web_dist
+	rm -rf mtv_agent/data/skills mtv_agent/data/playbooks
+	cp -r skills mtv_agent/data/skills
+	cp -r playbooks mtv_agent/data/playbooks
+	uv build
+
+## Show this help
+help:
+	@grep -B1 -E '^[a-zA-Z_-]+:' $(MAKEFILE_LIST) \
+	  | grep -v '^\-\-$$' \
+	  | awk '/^##/ {desc=substr($$0,4)} /^[a-zA-Z_-]+:/ {printf "  \033[36m%-15s\033[0m %s\n", $$1, desc; desc=""}'

mtv_agent-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: mtv-agent
+Version: 0.1.0
+Summary: AI agent for MTV/Forklift VM migrations
+Requires-Python: >=3.11
+Requires-Dist: claude-openai-proxy
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: mcp
+Requires-Dist: openai
+Requires-Dist: pydantic-settings
+Requires-Dist: pyyaml
+Requires-Dist: sse-starlette
+Requires-Dist: uvicorn
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'

mtv_agent-0.1.0/README.md

@@ -0,0 +1,232 @@
+# mtv-agent
+
+AI agent for [MTV/Forklift](https://github.com/kubev2v/forklift) VM migrations,
+with a tool loop, MCP tool integration, and markdown-based skills and playbooks.
+
+## Quick start
+
+```bash
+pip install mtv-agent
+mtv-agent init
+```
+
+Then set your cluster credentials and start the agent:
+
+```bash
+export KUBE_API_URL=https://api.cluster.example.com:6443
+export KUBE_TOKEN=$(oc whoami -t)
+
+mtv-agent start             # with LM Studio (default)
+mtv-agent start --with-cop  # with Claude
+```
+
+Open `http://localhost:8000` in your browser.
+
+For the full walkthrough, see:
+
+- [docs/installation.md](docs/installation.md) -- prerequisites, install,
+  and workspace setup
+- [docs/quickstart.md](docs/quickstart.md) -- step-by-step guide from zero
+  to running agent
+- [docs/llm-backends.md](docs/llm-backends.md) -- LM Studio and Claude setup
+- [docs/development.md](docs/development.md) -- contributor setup, dev
+  workflows, and project structure
+- [web/README.md](web/README.md) -- web UI architecture, components, and
+  frontend development
+
+## CLI reference
+
+```
+mtv-agent init   [--dir DIR] [--force]
+mtv-agent start  [--with-cop] [--runtime docker|podman] [--host HOST] [--port PORT] [--config PATH] [--no-web]
+mtv-agent serve  [--host HOST] [--port PORT] [--config PATH] [--no-web]
+mtv-agent stop
+mtv-agent config
+```
+
+| Command | Description |
+|---|---|
+| `init` | Create a workspace at `~/.mtv-agent/` with config, skills, and playbooks |
+| `start` | Start MCP containers, optional LLM proxy, and the API server. `--no-web` disables static UI serving |
+| `serve` | Start only the API server (MCP/LLM must be running separately). `--no-web` disables static UI serving |
+| `stop` | Stop MCP containers and claude-openai-proxy |
+| `config` | Print default config.json to stdout |
+
+## Configuration
+
+All settings live in a single `config.json` file. After running `mtv-agent init`,
+your config is at `~/.mtv-agent/config.json`. The agent searches for a config in this
+order: `CONFIG` env var, then `./config.json`, then `~/.mtv-agent/config.json`.
+
+To print the default config (useful for piping or inspection):
+
+```bash
+mtv-agent config
+```
+
+```json
+{
+  "llm": {
+    "baseUrl": "http://localhost:1234/v1",
+    "apiKey": "lm-studio",
+    "model": null
+  },
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000
+  },
+  "mcpServers": {
+    "kubectl-mtv": { "url": "http://localhost:8080/sse" },
+    "kubectl-metrics": { "url": "http://localhost:8081/sse" },
+    "kubectl-debug-queries": { "url": "http://localhost:8082/sse" }
+  },
+  "skills": { "dir": "./skills", "maxActive": 3 },
+  "playbooks": { "dir": "./playbooks" },
+  "memory": { "maxTurns": 20, "ttlSeconds": 3600, "toolResultLimit": 4000 },
+  "agent": {
+    "contextWindow": 30000,
+    "maxIterations": 20,
+    "maxRetries": 2,
+    "retryDelay": 2.0
+  }
+}
+```
+
+Every value can be overridden by an environment variable (no prefix needed):
+
+| Variable | Config key | Default | Description |
+|---|---|---|---|
+| `LLM_BASE_URL` | `llm.baseUrl` | `http://localhost:1234/v1` | OpenAI-compatible endpoint |
+| `LLM_API_KEY` | `llm.apiKey` | `lm-studio` | API key for the LLM server |
+| `LLM_MODEL` | `llm.model` | auto-discovered | Model name (queries `/v1/models` if unset) |
+| `SERVER_HOST` | `server.host` | `0.0.0.0` | API server bind address |
+| `SERVER_PORT` | `server.port` | `8000` | API server port |
+| `SKILLS_DIR` | `skills.dir` | bundled skills | Directory containing skill definitions |
+| `PLAYBOOKS_DIR` | `playbooks.dir` | bundled playbooks | Directory containing playbooks |
+| `MAX_ACTIVE_SKILLS` | `skills.maxActive` | `3` | Maximum skills active at once |
+| `MEMORY_MAX_TURNS` | `memory.maxTurns` | `20` | Conversation turns kept per session |
+| `MEMORY_TTL_SECONDS` | `memory.ttlSeconds` | `3600` | Seconds before a session is evicted |
+| `CONTEXT_WINDOW` | `agent.contextWindow` | `30000` | Default context window (overridden if auto-detected) |
+| `MAX_ITERATIONS` | `agent.maxIterations` | `20` | Maximum tool-loop iterations |
+| `MAX_RETRIES` | `agent.maxRetries` | `2` | LLM request retries on failure |
+| `RETRY_DELAY` | `agent.retryDelay` | `2.0` | Seconds between LLM retries |
+
+## Architecture
+
+`mtv-agent start` manages five components:
+
+| Component | Port | Description |
+|---|---|---|
+| API server | 8000 | FastAPI app serving the chat API and web UI |
+| kubectl-mtv MCP | 8080 | MTV/Forklift resource queries and mutations |
+| kubectl-metrics MCP | 8081 | Prometheus/Thanos metric queries |
+| kubectl-debug-queries MCP | 8082 | Kubernetes resources, logs, and events |
+| claude-openai-proxy | 1234 | Claude-to-OpenAI adapter (only with `--with-cop`) |
+
+The MCP containers are managed automatically. If you run them yourself,
+configure their URLs in `config.json` under `mcpServers`.
+
+## Skills and playbooks
+
+`mtv-agent init` copies the default skills and playbooks into `~/.mtv-agent/` so
+you can edit or extend them.
+
+**Skills** are markdown reference guides the agent loads on demand. Each skill
+lives in `~/.mtv-agent/skills/<name>/SKILL.md` with YAML frontmatter (`name`,
+`description`) and instruction body.
+
+**Playbooks** are task-oriented markdown files exposed in the web UI. They
+live in `~/.mtv-agent/playbooks/`. Override the directory with `SKILLS_DIR` or
+`PLAYBOOKS_DIR`.
+
+## API
+
+All API endpoints are served under the `/api` prefix.
+
+### `POST /api/chat`
+
+Non-streaming. Returns the complete answer as JSON.
+
+```bash
+curl -X POST http://localhost:8000/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "hello"}'
+```
+
+Request body:
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | string | The user message (required) |
+| `session_id` | string | Session ID for conversation history (auto-generated if omitted) |
+| `skills` | string[] | Skill names to activate |
+| `context` | object | Key-value context pairs (e.g. `{"namespace": "default"}`) |
+
+### `POST /api/chat/stream`
+
+Streaming. Emits SSE events as the agent works. Add `?approve=true` to require
+manual approval before each tool execution.
+
+SSE event types:
+
+| Event | Description |
+|---|---|
+| `session` | `{"session_id": "..."}` |
+| `thinking` | Agent is waiting for the LLM |
+| `usage` | Token usage: `total_tokens`, `prompt_tokens`, `completion_tokens`, `context_window` |
+| `tool_call` | Tool about to run: `name`, `arguments` |
+| `tool_result` | Tool finished: `name`, `result` |
+| `tool_denied` | Tool denied by user: `name`, `reason` |
+| `skill_selected` | Skill activated: `name` |
+| `skill_cleared` | All skills deactivated |
+| `context_set` | Context updated: `key`, `value` |
+| `context_unset` | Context key removed: `key` |
+| `content` | Final assistant response text |
+| `done` | Stream complete, includes final `content` |
+
+### `POST /api/chat/{session_id}/approve`
+
+Push an approval decision for a pending tool call (used with `?approve=true`).
+
+```json
+{"approved": true}
+```
+
+Or deny with an optional reason:
+
+```json
+{"approved": false, "reason": "too dangerous"}
+```
+
+### `GET /api/status`
+
+Returns model, MCP servers, tool count, context window, and max active skills.
+
+### `GET /api/models`
+
+Lists models available on the LLM server.
+
+### `PUT /api/model`
+
+Hot-swap the active model: `{"model": "model-name"}`.
+
+### `GET /api/skills`
+
+Lists available skills with names and descriptions.
+
+### `GET /api/playbooks`
+
+Lists available playbooks with metadata and body.
+
+### `GET /api/mcp`
+
+Lists all configured MCP servers with their connection status.
+
+### `POST /api/mcp/{name}` / `DELETE /api/mcp/{name}`
+
+Connect or disconnect an MCP server by name.
+
+## Development
+
+See [docs/development.md](docs/development.md) for contributor setup,
+dev workflows, make targets, and project structure.

mtv_agent-0.1.0/config.json.example

@@ -0,0 +1,43 @@
+{
+  "llm": {
+    "baseUrl": "http://localhost:1234/v1",
+    "apiKey": "lm-studio",
+    "model": null
+  },
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000
+  },
+  "mcpServers": {
+    "kubectl-mtv": {
+      "url": "http://localhost:8080/sse"
+    },
+    "kubectl-metrics": {
+      "url": "http://localhost:8081/sse"
+    },
+    "kubectl-debug-queries": {
+      "url": "http://localhost:8082/sse"
+    }
+  },
+  "skills": {
+    "dir": "./skills",
+    "maxActive": 3
+  },
+  "playbooks": {
+    "dir": "./playbooks"
+  },
+  "memory": {
+    "maxTurns": 20,
+    "ttlSeconds": 3600,
+    "toolResultLimit": 4000
+  },
+  "agent": {
+    "contextWindow": 30000,
+    "maxIterations": 20,
+    "maxRetries": 2,
+    "retryDelay": 2.0
+  },
+  "cache": {
+    "dir": ".cache/mtv-agent"
+  }
+}

mtv_agent-0.1.0/docs/development.md

@@ -0,0 +1,147 @@
+# Development
+
+This guide is for contributors working from a git checkout of the
+[mtv-agent](https://github.com/kubev2v/mtv-agent) repository.
+
+## Setup from source
+
+```bash
+git clone https://github.com/kubev2v/mtv-agent.git
+cd mtv-agent
+uv sync --extra dev
+```
+
+This creates a `.venv/`, installs all dependencies, and sets up the package
+in editable mode. To activate the venv in your shell (optional -- `uv run`
+handles this automatically):
+
+```bash
+source .venv/bin/activate
+```
+
+For the web UI you also need Node.js (v18+):
+
+```bash
+cd web && npm ci && cd ..
+```
+
+## Running in dev mode
+
+Set your cluster credentials once per shell session:
+
+```bash
+export KUBE_API_URL=https://api.cluster.example.com:6443
+export KUBE_TOKEN=$(oc whoami -t)
+```
+
+Then use the Make targets:
+
+```bash
+make run        # MCP containers + API server (uses local LLM)
+make run-cop    # same, but also starts claude-openai-proxy
+make build-web  # build the web UI into web/dist/ (served automatically)
+make stop       # stop MCP containers and claude-openai-proxy
+```
+
+The API server auto-detects `web/dist/` and serves it at
+`http://localhost:8000`. If you haven't built the web UI yet, the API
+still works -- you just won't see the browser interface.
+
+## Frontend development
+
+For frontend work you want the Vite dev server (with hot-module reload)
+alongside the API server. Run them in two terminals:
+
+```bash
+# Terminal 1 -- API server without static file serving
+make dev
+
+# Terminal 2 -- Vite dev server on port 5173
+make dev-web
+```
+
+`make dev` sets `NO_WEB=1` so the API server does not serve static files,
+avoiding conflicts with Vite. The Vite dev server proxies `/api` requests
+to the API server on port 8000 automatically.
+
+## Make targets reference
+
+| Target | Description |
+|---|---|
+| `make run` | Start MCP containers + API server via `scripts/run.sh` |
+| `make run-cop` | Same as `run` but also starts claude-openai-proxy |
+| `make dev` | Start MCP containers + API server with `--no-web` (for frontend dev) |
+| `make serve` | Start only the API server (no containers) |
+| `make build-web` | Build the web UI into `web/dist/` |
+| `make dev-web` | Start the Vite dev server for the web UI |
+| `make stop` | Stop MCP containers and claude-openai-proxy |
+| `make format` | Auto-format Python code with ruff |
+| `make format-web` | Auto-format web code with prettier |
+| `make lint` | Lint Python code with ruff |
+| `make lint-web` | Lint web code with eslint + prettier |
+| `make package` | Build the pip-distributable wheel (includes web UI) |
+| `make help` | Show all targets |
+
+## Linting and formatting
+
+```bash
+make lint       # ruff check + format check
+make format     # ruff auto-fix + format
+
+make lint-web   # eslint + prettier check
+make format-web # prettier auto-fix
+```
+
+## Building the pip package
+
+```bash
+make package
+```
+
+This runs `make build-web` first, copies `web/dist/` into `mtv_agent/web_dist/`,
+then runs `python -m build` to produce a distributable wheel in `dist/`.
+
+## Project structure
+
+```
+mtv-agent/
+├── mtv_agent/               # Python package (pip-installable)
+│   ├── __init__.py          # Version
+│   ├── __main__.py          # python -m mtv_agent
+│   ├── cli.py               # CLI entry point (mtv-agent command)
+│   ├── orchestrator.py      # Container + process lifecycle management
+│   ├── main.py              # FastAPI app, /api endpoints, static serving
+│   ├── agent.py             # The tool loop (LLM -> tools -> results -> LLM)
+│   ├── config.py            # Settings (config.json + env-var overrides)
+│   ├── lib/                 # Internal libraries
+│   │   ├── bash_tool.py     # Built-in bash tool for shell commands
+│   │   ├── chat_store.py    # Persistent chat storage (JSON files)
+│   │   ├── llm.py           # OpenAI-compatible LLM client
+│   │   ├── mcp_client.py    # MCP SSE client
+│   │   ├── mcp_manager.py   # Multi-MCP server manager
+│   │   ├── memory.py        # In-memory conversation history
+│   │   ├── playbooks.py     # Playbook markdown loader
+│   │   ├── skills.py        # Skill markdown loader
+│   │   ├── system_prompt.py # System prompt builder
+│   │   ├── text_utils.py    # Truncation, frontmatter parsing
+│   │   ├── tool_registry.py # Unified registry (bash + MCP tools)
+│   │   └── virtual_tools.py # select_skill, set_context tools
+│   └── data/                # Bundled data (included in pip package)
+│       ├── config.json.example
+│       ├── skills/
+│       └── playbooks/
+├── web/                     # Web UI source (Lit + TypeScript, not packaged)
+│   ├── src/
+│   ├── dist/                # Built assets (served by Python server)
+│   └── package.json
+├── docs/                    # Documentation
+│   ├── installation.md      # Prerequisites, install, workspace setup
+│   ├── quickstart.md        # Zero-to-running walkthrough
+│   ├── llm-backends.md      # LM Studio and Claude setup guide
+│   └── development.md       # This file
+├── skills/                  # Dev skills (used by make run)
+├── playbooks/               # Dev playbooks (used by make run)
+├── scripts/run.sh           # Dev launcher script
+├── Makefile                 # Dev and build targets
+└── pyproject.toml           # Package metadata and dependencies
+```

mtv_agent-0.1.0/docs/installation.md

@@ -0,0 +1,83 @@
+# Installation
+
+## Prerequisites
+
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** -- fast Python package manager
+  (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- **Docker or Podman** -- used to run the three MCP server containers that
+  give the agent access to your OpenShift cluster
+- **An OpenShift cluster** with [MTV/Forklift](https://github.com/kubev2v/forklift)
+  installed
+- **An OpenAI-compatible LLM server** -- either
+  [LM Studio](https://lmstudio.ai) (local) or
+  [Claude](https://docs.anthropic.com/en/docs/claude-code) via the bundled
+  proxy. See [llm-backends.md](llm-backends.md) for details.
+
+## Install from pip
+
+```bash
+pip install mtv-agent
+```
+
+This installs the `mtv-agent` command along with all Python dependencies,
+including `claude-openai-proxy`.
+
+Verify the installation:
+
+```bash
+mtv-agent --version
+```
+
+## Install from source
+
+For contributors or if you want to run from a git checkout:
+
+```bash
+git clone https://github.com/yaacov/mtv-agent.git
+cd mtv-agent
+uv sync --extra dev
+```
+
+`uv sync` creates the virtual environment automatically (in `.venv/`),
+installs all dependencies, and sets up the package in editable mode.
+Code changes take effect immediately.
+
+## Initialise a workspace
+
+After installing, run `init` to create a local workspace with the default
+configuration, skills, and playbooks:
+
+```bash
+mtv-agent init
+```
+
+This creates `~/.mtv-agent/` with:
+
+```
+~/.mtv-agent/
+├── config.json     # agent settings (LLM, server, MCP, memory, etc.)
+├── skills/         # markdown reference guides the agent can load on demand
+└── playbooks/      # task playbooks exposed in the web UI
+```
+
+You can edit any of these files to customise the agent's behaviour.
+
+### Options
+
+Initialise into a custom directory:
+
+```bash
+mtv-agent init --dir ./my-workspace
+```
+
+Reset an existing workspace back to defaults:
+
+```bash
+mtv-agent init --force
+```
+
+## What's next
+
+Follow the [Quick Start](quickstart.md) guide to set up an LLM backend and
+launch the agent.