kiteml-cli 0.1.0__tar.gz

kiteml_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

kiteml_cli-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: kiteml-cli
+Version: 0.1.0
+Summary: Kite CLI and MCP server: train robot policies with reinforcement learning in simulation, augment LeRobot datasets, and build MuJoCo digital twins, from your terminal or an AI agent.
+Project-URL: Homepage, https://kiteml.com
+Project-URL: Documentation, https://kite-ml.mintlify.app/tools/cli-and-mcp
+Project-URL: API reference, https://kite-ml.mintlify.app/platform-api/overview
+Project-URL: Dashboard, https://app.kiteml.com
+Project-URL: MCP server, https://mcp.kiteml.com/mcp
+Project-URL: Blog, https://kiteml.com/blog
+Author-email: Kite ML <raul@kiteml.com>
+License-Expression: Apache-2.0
+Keywords: ai agents,claude,cli,cursor,data augmentation,dataset augmentation,digital twin,humanoid,imitation learning,kite,legged robots,lerobot,mcp,mcp-server,model context protocol,mujoco,onnx,policy evaluation,policy training,reinforcement learning,rl,robot learning,robot policy,robotics,sim-to-real,simulation,vla
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: all
+Requires-Dist: mcp<2,>=1.0; extra == 'all'
+Requires-Dist: starlette>=0.37; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mcp<2,>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
+Requires-Dist: starlette>=0.37; extra == 'mcp'
+Requires-Dist: uvicorn>=0.30; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Kite CLI and MCP server
+
+Robot learning on cloud GPUs, from your terminal or your AI agent. Kite trains robot policies with
+reinforcement learning in simulation, augments LeRobot datasets, and rebuilds robot episodes as MuJoCo digital
+twins. This package gives you the `kite` command line and the `kite-mcp` server for Claude, Cursor, and any
+Model Context Protocol (MCP) client.
+
+<!-- mcp-name: com.kiteml/kite -->
+
+- **RL training in simulation.** Describe a behavior in plain English. Kite writes the task spec, checks its
+  rewards for free, and trains the policy on a GPU. You get the policy as ONNX, the MuJoCo scene it trained in, and
+  clips.
+- **Policy evaluation.** Every RL run ends with a report: a pass, needs_review or fail verdict from measured checks
+  (falls per minute, survival, command tracking, gait, posture), plus a vision model's read of the clip.
+- **Dataset augmentation.** Relight a LeRobot dataset to match a deployment scene, or generate new variations of
+  it with video augmentation. Output is a standard LeRobot dataset (Parquet + MP4), downloaded or pushed to
+  Hugging Face.
+- **Digital twins.** Point Kite at one episode of a LeRobot dataset and get an interactable MuJoCo scene of the
+  room, with the objects the robot handles built to size.
+
+## Install
+
+```bash
+pip install "kiteml-cli[mcp]"
+```
+
+Python 3.10 or later. Drop `[mcp]` if you only want the CLI.
+
+## Sign in
+
+```bash
+kite auth login     # opens the dashboard; stores a 90-day API key
+kite doctor         # checks the API is reachable and your key works
+```
+
+On a server or in CI, set an API key from [app.kiteml.com](https://app.kiteml.com) instead:
+
+```bash
+export KITE_API_KEY=kite_...
+```
+
+## Use it from an AI agent
+
+Kite hosts the MCP server, so there's nothing to run:
+
+```bash
+claude mcp add --transport http kite https://mcp.kiteml.com/mcp
+```
+
+Or run it locally over stdio with this package:
+
+```bash
+claude mcp add kite -e KITE_API_KEY=$KITE_API_KEY -- kite-mcp
+```
+
+For Cursor and other clients, add `{"mcpServers": {"kite": {"url": "https://mcp.kiteml.com/mcp"}}}` to the MCP
+config. Then ask, for example: "train the Open Duck Mini to walk forward and tell me when it passes", or "relight
+lerobot/pusht to look like this photo".
+
+| Tools | What they do |
+| --- | --- |
+| `kite_rl_catalog`, `kite_rl_plan`, `kite_rl_validate` | See which robots and objectives RL runs support, and plan and check a training spec for free |
+| `kite_rl_train`, `kite_rl_fork`, `kite_rl_cancel` | Start, branch from, and stop RL runs |
+| `kite_rl_status`, `kite_rl_metrics`, `kite_rl_report`, `kite_rl_list` | Follow training and read each run's evaluation verdict |
+| `kite_augment_create`, `kite_augment_status`, `kite_augment_list`, `kite_augment_cancel` | Augment LeRobot datasets |
+| `kite_twin_validate`, `kite_twin_create`, `kite_twin_status`, `kite_twin_list`, `kite_twin_cancel`, `kite_twin_resume` | Build MuJoCo digital twins |
+| `kite_doctor` | Check connectivity and authentication |
+
+## Use it from the terminal
+
+Train a walking policy for the Open Duck Mini v2:
+
+```bash
+kite rl plan open_duck_mini_v2 "walk forward at a steady pace" -o walk.json
+kite rl validate walk.json                 # free: what each reward term pays canned policies
+kite rl train walk.json --budget probe --wait
+kite rl report rlr_...                     # the verdict and each check behind it
+kite rl download rlr_...                   # -> kiteml_rlr_.../policy/policy.onnx
+```
+
+Augment a dataset:
+
+```bash
+kite augment create --repo-id lerobot/pusht \
+  -i "change the table surface to white marble, vary the lighting" -n 20 --wait
+kite augment download aug_... -o ./pusht-marble
+```
+
+Build a digital twin (private beta):
+
+```bash
+kite twin create lerobot/svla_so101_pickplace --out ./twins   # -> ./twins/twin_.../scene.xml
+```
+
+Every command prints JSON (`{"ok": true, "data": ...}`) so scripts and agents can parse it. Run `kite --help` for
+the full list.
+
+## Links
+
+- Docs: [CLI and MCP](https://kite-ml.mintlify.app/tools/cli-and-mcp) ·
+  [RL runs](https://kite-ml.mintlify.app/platform-api/rl-runs) ·
+  [Augmentations](https://kite-ml.mintlify.app/platform-api/augmentation) ·
+  [Twins](https://kite-ml.mintlify.app/platform-api/twins)
+- Dashboard: [app.kiteml.com](https://app.kiteml.com)
+- Website: [kiteml.com](https://kiteml.com)
+- Support: [raul@kiteml.com](mailto:raul@kiteml.com)

kiteml_cli-0.1.0/README.md

@@ -0,0 +1,106 @@
+# Kite CLI and MCP server
+
+Robot learning on cloud GPUs, from your terminal or your AI agent. Kite trains robot policies with
+reinforcement learning in simulation, augments LeRobot datasets, and rebuilds robot episodes as MuJoCo digital
+twins. This package gives you the `kite` command line and the `kite-mcp` server for Claude, Cursor, and any
+Model Context Protocol (MCP) client.
+
+<!-- mcp-name: com.kiteml/kite -->
+
+- **RL training in simulation.** Describe a behavior in plain English. Kite writes the task spec, checks its
+  rewards for free, and trains the policy on a GPU. You get the policy as ONNX, the MuJoCo scene it trained in, and
+  clips.
+- **Policy evaluation.** Every RL run ends with a report: a pass, needs_review or fail verdict from measured checks
+  (falls per minute, survival, command tracking, gait, posture), plus a vision model's read of the clip.
+- **Dataset augmentation.** Relight a LeRobot dataset to match a deployment scene, or generate new variations of
+  it with video augmentation. Output is a standard LeRobot dataset (Parquet + MP4), downloaded or pushed to
+  Hugging Face.
+- **Digital twins.** Point Kite at one episode of a LeRobot dataset and get an interactable MuJoCo scene of the
+  room, with the objects the robot handles built to size.
+
+## Install
+
+```bash
+pip install "kiteml-cli[mcp]"
+```
+
+Python 3.10 or later. Drop `[mcp]` if you only want the CLI.
+
+## Sign in
+
+```bash
+kite auth login     # opens the dashboard; stores a 90-day API key
+kite doctor         # checks the API is reachable and your key works
+```
+
+On a server or in CI, set an API key from [app.kiteml.com](https://app.kiteml.com) instead:
+
+```bash
+export KITE_API_KEY=kite_...
+```
+
+## Use it from an AI agent
+
+Kite hosts the MCP server, so there's nothing to run:
+
+```bash
+claude mcp add --transport http kite https://mcp.kiteml.com/mcp
+```
+
+Or run it locally over stdio with this package:
+
+```bash
+claude mcp add kite -e KITE_API_KEY=$KITE_API_KEY -- kite-mcp
+```
+
+For Cursor and other clients, add `{"mcpServers": {"kite": {"url": "https://mcp.kiteml.com/mcp"}}}` to the MCP
+config. Then ask, for example: "train the Open Duck Mini to walk forward and tell me when it passes", or "relight
+lerobot/pusht to look like this photo".
+
+| Tools | What they do |
+| --- | --- |
+| `kite_rl_catalog`, `kite_rl_plan`, `kite_rl_validate` | See which robots and objectives RL runs support, and plan and check a training spec for free |
+| `kite_rl_train`, `kite_rl_fork`, `kite_rl_cancel` | Start, branch from, and stop RL runs |
+| `kite_rl_status`, `kite_rl_metrics`, `kite_rl_report`, `kite_rl_list` | Follow training and read each run's evaluation verdict |
+| `kite_augment_create`, `kite_augment_status`, `kite_augment_list`, `kite_augment_cancel` | Augment LeRobot datasets |
+| `kite_twin_validate`, `kite_twin_create`, `kite_twin_status`, `kite_twin_list`, `kite_twin_cancel`, `kite_twin_resume` | Build MuJoCo digital twins |
+| `kite_doctor` | Check connectivity and authentication |
+
+## Use it from the terminal
+
+Train a walking policy for the Open Duck Mini v2:
+
+```bash
+kite rl plan open_duck_mini_v2 "walk forward at a steady pace" -o walk.json
+kite rl validate walk.json                 # free: what each reward term pays canned policies
+kite rl train walk.json --budget probe --wait
+kite rl report rlr_...                     # the verdict and each check behind it
+kite rl download rlr_...                   # -> kiteml_rlr_.../policy/policy.onnx
+```
+
+Augment a dataset:
+
+```bash
+kite augment create --repo-id lerobot/pusht \
+  -i "change the table surface to white marble, vary the lighting" -n 20 --wait
+kite augment download aug_... -o ./pusht-marble
+```
+
+Build a digital twin (private beta):
+
+```bash
+kite twin create lerobot/svla_so101_pickplace --out ./twins   # -> ./twins/twin_.../scene.xml
+```
+
+Every command prints JSON (`{"ok": true, "data": ...}`) so scripts and agents can parse it. Run `kite --help` for
+the full list.
+
+## Links
+
+- Docs: [CLI and MCP](https://kite-ml.mintlify.app/tools/cli-and-mcp) ·
+  [RL runs](https://kite-ml.mintlify.app/platform-api/rl-runs) ·
+  [Augmentations](https://kite-ml.mintlify.app/platform-api/augmentation) ·
+  [Twins](https://kite-ml.mintlify.app/platform-api/twins)
+- Dashboard: [app.kiteml.com](https://app.kiteml.com)
+- Website: [kiteml.com](https://kiteml.com)
+- Support: [raul@kiteml.com](mailto:raul@kiteml.com)

kiteml_cli-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kiteml-cli"
+version = "0.1.0"
+description = "Kite CLI and MCP server: train robot policies with reinforcement learning in simulation, augment LeRobot datasets, and build MuJoCo digital twins, from your terminal or an AI agent."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Kite ML", email = "raul@kiteml.com" }]
+keywords = [
+    "robotics", "robot learning", "reinforcement learning", "rl", "sim-to-real", "simulation", "mujoco",
+    "robot policy", "policy training", "policy evaluation", "lerobot", "imitation learning", "vla",
+    "data augmentation", "dataset augmentation", "digital twin", "humanoid", "legged robots", "onnx",
+    "mcp", "mcp-server", "model context protocol", "ai agents", "claude", "cursor", "cli", "kite",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "typer>=0.9",
+    "httpx>=0.25",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://kiteml.com"
+Documentation = "https://kite-ml.mintlify.app/tools/cli-and-mcp"
+"API reference" = "https://kite-ml.mintlify.app/platform-api/overview"
+Dashboard = "https://app.kiteml.com"
+"MCP server" = "https://mcp.kiteml.com/mcp"
+Blog = "https://kiteml.com/blog"
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0,<2", "uvicorn>=0.30", "starlette>=0.37"]
+all = ["kiteml-cli[mcp]"]
+dev = [
+    "kiteml-cli[all]",
+    "pytest>=7.0",
+    "pytest-asyncio",
+    "ruff",
+]
+
+[project.scripts]
+kite = "kite_cli.cli.main:app"
+kite-mcp = "kite_cli.mcp.server:main"
+
+# The published package is the public /v1 client. kite_cli/internal (the dashboard's commands and tools, and the
+# hosted server's HTTP transport) stays in this repo: the hosted image puts the source tree on PYTHONPATH instead.
+[tool.hatch.build.targets.wheel]
+packages = ["src/kite_cli"]
+exclude = ["src/kite_cli/internal"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/kite_cli", "README.md", "pyproject.toml"]
+exclude = ["src/kite_cli/internal"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

kiteml_cli-0.1.0/src/kite_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Kite CLI and MCP server for the Kite robotics training platform."""
+
+__version__ = "0.1.0"

kiteml_cli-0.1.0/src/kite_cli/auth.py

@@ -0,0 +1,184 @@
+"""
+Authentication for the Kite CLI.
+
+Supports:
+  - API key: KITE_API_KEY env var (recommended for MCP / programmatic access)
+  - Browser OAuth: `kite auth login` opens the dashboard in a browser → an API key is stored
+  - Environment variable: KITE_TOKEN for CI/headless
+  - Token file: ~/.kite/credentials.json (written by login, read by client)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import sys
+import threading
+import time
+import webbrowser
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Optional
+from urllib.parse import parse_qs, urlparse
+
+from kite_cli.config import KITE_DIR, get_app_url
+
+CREDENTIALS_PATH = KITE_DIR / "credentials.json"
+
+
+def get_token() -> Optional[str]:
+    """Get a valid auth token. Checks env vars first, then credentials file."""
+    # 1. API key (MCP / programmatic access)
+    api_key = os.environ.get("KITE_API_KEY")
+    if api_key:
+        return api_key
+
+    # 2. Token override (CI, headless)
+    env_token = os.environ.get("KITE_TOKEN")
+    if env_token:
+        return env_token
+
+    # 3. Stored credentials
+    creds = _load_credentials()
+    if creds and creds.get("id_token"):
+        return creds["id_token"]
+
+    return None
+
+
+def save_credentials(id_token: str, user_info: Optional[dict] = None) -> None:
+    """Save credentials to disk with restricted permissions."""
+    KITE_DIR.mkdir(parents=True, exist_ok=True)
+    creds = {
+        "id_token": id_token,
+        "user_info": user_info,
+        "saved_at": time.time(),
+    }
+    CREDENTIALS_PATH.write_text(json.dumps(creds, indent=2) + "\n")
+    # Restrict file permissions (owner read/write only)
+    try:
+        CREDENTIALS_PATH.chmod(0o600)
+    except OSError:
+        pass
+
+
+def clear_credentials() -> None:
+    """Remove stored credentials."""
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+
+
+def _load_credentials() -> Optional[dict]:
+    """Load credentials from disk."""
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        return json.loads(CREDENTIALS_PATH.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """HTTP handler that receives the OAuth callback with the token."""
+
+    token: Optional[str] = None
+    user_info: Optional[dict] = None
+    expected_state: Optional[str] = None
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        params = parse_qs(parsed.query)
+
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+
+        state = params.get("state", [None])[0]
+        token = params.get("token", [None])[0]
+        email = params.get("email", [None])[0]
+
+        # Only accept the login this process started. Without this, any local
+        # page could hit the ephemeral port and plant a token. compare_digest
+        # keeps the nonce from being probed a byte at a time.
+        expected = _CallbackHandler.expected_state
+        if not expected or not state or not secrets.compare_digest(state, expected):
+            self._reply(403, "Login failed", "This callback did not come from the login you started.")
+            return
+
+        if not token:
+            self._reply(400, "Login failed", "No token received.")
+            return
+
+        _CallbackHandler.token = token
+        _CallbackHandler.user_info = {"email": email} if email else None
+        self._reply(200, "Login successful!", "You can close this tab.")
+
+    def _reply(self, status: int, heading: str, detail: str) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(f"<html><body><h2>{heading}</h2><p>{detail}</p></body></html>".encode())
+
+    def log_message(self, format, *args):
+        pass  # Suppress HTTP server logs
+
+
+def login_browser(timeout: int = 120) -> bool:
+    """Open browser for OAuth login. Returns True on success."""
+    import socket
+
+    # Find a free port
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+
+    # Single-use nonce the /cli-auth page echoes back, so we can tell our own
+    # callback apart from any other request that reaches this port.
+    state = secrets.token_urlsafe(24)
+
+    # Reset handler state
+    _CallbackHandler.token = None
+    _CallbackHandler.user_info = None
+    _CallbackHandler.expected_state = state
+
+    server = HTTPServer(("127.0.0.1", port), _CallbackHandler)
+    # Poll in short slices so a stray request can't hold us past the deadline.
+    server.timeout = 1
+
+    # The dashboard's /cli-auth page signs you in, then redirects to our
+    # loopback callback with the token. Derive nothing from the API URL: the
+    # app is a different host (app.kiteml.com vs api.kiteml.com).
+    login_url = f"{get_app_url().rstrip('/')}/cli-auth?redirect_port={port}&state={state}"
+
+    print(f"Opening browser for login...")
+    print(f"If the browser doesn't open, visit: {login_url}")
+    webbrowser.open(login_url)
+
+    # Wait for callback
+    deadline = time.time() + timeout
+    while time.time() < deadline and _CallbackHandler.token is None:
+        server.handle_request()
+
+    server.server_close()
+
+    if _CallbackHandler.token:
+        save_credentials(
+            id_token=_CallbackHandler.token,
+            user_info=_CallbackHandler.user_info,
+        )
+        return True
+
+    return False
+
+
+def login_headless() -> bool:
+    """Headless login: prompt user to paste a token."""
+    print("Visit your Kite dashboard to generate an API token.")
+    print("Then paste it here:")
+    token = input("> ").strip()
+    if token:
+        save_credentials(id_token=token)
+        return True
+    return False