colabctl 0.1.0__tar.gz

colabctl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: lint · types · tests (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+
+      - name: Sync (all extras + dev)
+        run: uv sync --all-extras
+
+      - name: Ruff lint
+        run: uv run ruff check src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: Mypy (strict)
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest -q
+
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

colabctl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Publishes on a version tag (e.g. `v0.1.0`). Uses PyPI Trusted Publishing
+# (GitHub OIDC) — no API token is stored in the repo.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/):
+#   project: colabctl · owner: mandipadk · repo: colabctl · workflow: publish.yml
+#   environment: pypi
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    name: build + publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        run: uv publish --trusted-publishing always

colabctl-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Builds
+/dist/
+/build/
+/site/                     # mkdocs output
+
+# Tooling caches
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Spike outputs / local artifacts
+spikes/phase0-results.txt
+spikes/phase0_*.txt
+spikes/phase0_*.png
+
+# Secrets / local config (never commit)
+.env
+*.token.json

colabctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-08
+
+First public release. Programmatic Google Colab control plus a multi-backend job API.
+
+### Added
+
+- **Transports** behind a single `TransportAdapter` contract:
+  - `cli` — wraps the official `google-colab-cli` (sanctioned default), with a
+    golden-tested stdout parser pinned to v0.5.7.
+  - `native` — from-scratch `/tun/m/*` client + Jupyter-websocket kernel (co-primary,
+    opt-in). Both **live-validated** against real Colab Pro.
+- **Auth** — ADC-led providers (the Phase 0-verified path) + scope constants.
+- **Secrets** — one `SecretStore` contract over keyring (chunked), an encrypted file
+  (headless/CI), and an in-memory store.
+- **SDK** — `ColabClient` / `ColabSession` (async, context-managed) and the `@remote`
+  decorator (ship a local function to a GPU via cloudpickle).
+- **CLI** — `colabctl` (Typer): `run`, `exec`, `new`, `sessions`, `status`, `stop`,
+  `upload`, `download`, `keepalive`, and `job run` / `job backends`.
+- **MCP server** — `colabctl-mcp` (FastMCP) exposing 9 tools (interactive + batch-job)
+  so AI agents can drive Colab, Modal, and Vertex.
+- **Provider abstraction** — `Backend` (submit/status/logs/result/cancel) + a
+  capability-routing `BackendRouter` with infra failover, plus the **Colab**,
+  **Modal** (live-validated), **Vertex AI**, **Hugging Face Jobs**, and **Kaggle**
+  backends, wired into the CLI (`colabctl job …`) and MCP.
+- **Browser-bridge transport** (colab-mcp model) — JSON-RPC relay over a local
+  WebSocket; human-in-the-loop, needs live validation.
+- **Runtime-lifecycle manager** — best-effort keep-alive ticks + proactive checkpoint
+  + automatic re-assign/restore on idle reclamation.
+- **Drive sync** — `DriveSync` (durable My-Drive file sync via user-OAuth) + lifecycle
+  checkpoint/restore hooks.
+- **Observability** — namespaced logging + a reusable `retry_async` (exponential
+  backoff that never retries terminal quota/entitlement errors).
+- **Spend guard** — `cap_timeout` enforces a hard billable-time ceiling on paid
+  backends (wired into Modal).
+
+### Known limitations
+
+- The Colab RuntimeService keep-alive RPC is unusable under token auth (live-confirmed);
+  long jobs rely on kernel activity + checkpoint/re-assign instead.
+- Vertex stdout is in Cloud Logging (not captured); `result` returns state + a log link.
+- Vertex / Hugging Face / Kaggle backends and the browser-bridge are not yet
+  live-validated (no accounts in CI); their logic is unit-tested against fakes.
+- Still planned: RunPod/vast.ai + hyperscaler backends, a papermill notebook adapter,
+  a `jupyter_http_over_ws` integration test rig, a billing watchdog, and a docs site.
+
+[Unreleased]: https://github.com/mandipadk/colabctl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mandipadk/colabctl/releases/tag/v0.1.0

colabctl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to colabctl
+
+Thanks for helping build colabctl. This guide covers the dev workflow and the quality
+bar every change must clear.
+
+## Setup
+
+colabctl uses [uv](https://docs.astral.sh/uv/). Install it, then:
+
+```bash
+uv sync --all-extras       # creates .venv with every optional dependency + dev tools
+```
+
+## The quality gate (run before every commit)
+
+```bash
+uv run ruff check src tests        # lint
+uv run ruff format src tests       # format (use --check in CI)
+uv run mypy src                    # strict type-check
+uv run pytest -q                   # the full suite — offline, no credentials
+```
+
+CI runs exactly this on Python 3.11 / 3.12 / 3.13, plus `uv build`. All four must pass.
+
+## Conventions
+
+- **Strict typing.** `mypy --strict` must pass. Lazy-imported third-party SDKs are
+  listed under `[[tool.mypy.overrides]]` in `pyproject.toml`.
+- **Tests are offline.** No test may hit the network or need credentials. Live checks
+  live in `spikes/` and are run by hand against a real account.
+- **Transports/backends are pluggable.** New transports implement
+  `transport.base.TransportAdapter`; new backends implement `backends.base.Backend`.
+  Keep heavy/optional SDKs lazy-imported and declared as an extra.
+- **Be honest about limitations.** If something isn't live-validated or has a known
+  gap, say so in the docstring and the relevant doc — don't paper over it. (See the
+  keep-alive saga in `spikes/PHASE0-FINDINGS.md` for why.)
+- **Pin & verify external contracts.** When wrapping an external API/CLI, verify it
+  against current docs/source and pin the version; surface contract drift loudly.
+
+## Layout
+
+`SPEC.md` is the canonical architecture. `DIRECTIVES.md` records binding decisions.
+`spikes/` holds validation runbooks + findings. `src/colabctl/` is the package; see the
+README for the module map.