obsessiondb · Lucasgvdii · Aug 10, 2026 · Jun 5, 2026 · Jun 11, 2026 · Jun 24, 2026
diff --git a/.changeset/cli-skills-proxy.md b/.changeset/cli-skills-proxy.md
@@ -0,0 +1,5 @@
+---
+"chkit": patch
+---
+
+Add a `chkit skills` command that proxies to the external `skills` CLI (e.g. `chkit skills add obsessiondb/chkit` runs `npx skills add obsessiondb/chkit`). The agent skill is installed by the separate `skills` tool, not a chkit subcommand, so users who reached for `chkit skills add …` previously hit "Unknown command: skills". The command forwards its arguments and passes through the underlying exit code, and is handled before config loading so it works without a project.
diff --git a/.changeset/create-chkit-next-steps-dedup.md b/.changeset/create-chkit-next-steps-dedup.md
@@ -0,0 +1,6 @@
+---
+"create-chkit": patch
+"@chkit/plugin-obsessiondb": patch
+---
+
+Print the "Next steps" block once and with the correct runner for the selected package manager. `create-chkit` previously printed it twice — once package-manager-aware and once from onboarding with a hardcoded `bunx` — so `--package-manager npm` users were told to run `bunx chkit …`. Onboarding now derives the runner (`npx` / `pnpm dlx` / `yarn dlx` / `bunx`) from the package manager, and `create-chkit` only prints its own next-steps when onboarding is skipped, removing the duplicate.
diff --git a/.changeset/init-connect-runbook-consistency.md b/.changeset/init-connect-runbook-consistency.md
@@ -0,0 +1,5 @@
+---
+"chkit": patch
+---
+
+Make `chkit init` consistent with `create-chkit` for connecting a database, and stop hiding plugin import failures. In a non-TTY shell `init` now prints the same connect runbook `create-chkit` does (when the obsessiondb plugin is installed) instead of silently skipping it; `--yes` still keeps init a silent file-writer for CI. The dynamic plugin import now only degrades silently when the plugin is genuinely not installed — any other load failure propagates instead of a false silent pass. The static next-steps also use `npx` rather than a hardcoded `bunx`.
diff --git a/.changeset/migrate-async-poll-resilience.md b/.changeset/migrate-async-poll-resilience.md
@@ -0,0 +1,5 @@
+---
+"chkit": patch
+---
+
+Keep polling an async data-load migration through transient gateway errors instead of aborting. A single HTTP 524 (or other transient failure) on a status-poll request no longer cancels the migration: the server-side query keeps running, so chkit tolerates a bounded number of poll errors and only gives up after the budget, with an explicit message that the load may still be running and that re-running re-attaches via the deterministic `query_id`. Only a real query exception, or a submit-time failure, is fatal. This affects only operations marked `mode=async` (data loads); ordinary schema DDL is synchronous and unaffected.
diff --git a/.changeset/obsessiondb-json-no-bare-string.md b/.changeset/obsessiondb-json-no-bare-string.md
@@ -0,0 +1,6 @@
+---
+"@chkit/plugin-obsessiondb": patch
+"chkit": patch
+---
+
+Make `--json` always emit a JSON object, never a bare JSON-encoded string. `printOutput` now wraps any plain string printed under `--json` in `{ schemaVersion, message }`, closing the whole class of bug at the serializer so no command can leak a bare string. `chkit obsessiondb whoami` gains a structured envelope (`status: logged_in | not_logged_in | session_expired`), and `chkit obsessiondb service list` emits a single object with a `services[]` array instead of one JSON line per service (which was not valid single-JSON). Previously these commands `JSON.stringify`'d a prose string (e.g. `"Not logged in…"`), breaking any pipe to `jq`. Text-mode output is unchanged. Note: this changes the `--json` output shape of `whoami` and `service list` from a string to an object.
diff --git a/.changeset/obsessiondb-logout-no-session.md b/.changeset/obsessiondb-logout-no-session.md
@@ -0,0 +1,5 @@
+---
+"@chkit/plugin-obsessiondb": patch
+---
+
+`chkit obsessiondb logout` now reports "No active session." when there are no stored credentials, instead of always printing "Logged out." (which implied it had ended a session that never existed). Logout stays idempotent and exits 0 either way; only the message changes.
diff --git a/.changeset/pull-route-through-executor.md b/.changeset/pull-route-through-executor.md
@@ -0,0 +1,5 @@
+---
+"@chkit/plugin-pull": patch
+---
+
+Route `chkit pull` introspection through the host-provided executor instead of always opening its own ClickHouse connection. When an ObsessionDB service is selected, pull now introspects through the ObsessionDB API (the same executor `generate`/`migrate`/`status` use) rather than silently falling back to `http://localhost:8123` and failing with "connection refused" while printing `using service <name>`. A direct ClickHouse target is unchanged, custom introspectors still open their own raw connection, and a run with no reachable target now errors with an actionable message instead of a misleading localhost fallback.
diff --git a/.github/workflows/publish-chkit-py.yml b/.github/workflows/publish-chkit-py.yml
@@ -0,0 +1,66 @@
+name: Publish chkit-py to PyPI
+
+# Publishes on tags like `chkit-py-v0.2.0` via PyPI trusted publishing (OIDC):
+# no API tokens stored in the repo. One-time setup on pypi.org: project
+# `chkit-py` → Publishing → add a trusted publisher for
+# obsessiondb/chkit with workflow `publish-chkit-py.yml`.
+on:
+  push:
+    tags:
+      - "chkit-py-v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: chkit_python
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          tag="${GITHUB_REF_NAME#chkit-py-v}"
+          if [ "$version" != "$tag" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Smoke-test the wheel
+        run: |
+          python -m venv /tmp/wheeltest
+          /tmp/wheeltest/bin/pip install dist/*.whl
+          /tmp/wheeltest/bin/python -c "import chkit, chkit_plugin_backfill, chkit_plugin_codegen, chkit_plugin_obsessiondb; print(chkit.__version__)"
+          /tmp/wheeltest/bin/chkit --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: chkit-py-dist
+          path: chkit_python/dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: chkit-py-dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
diff --git a/README.md b/README.md
@@ -4,13 +4,13 @@
 
 # chkit
 
-**ClickHouse schema and migration CLI for TypeScript projects.**
+**ClickHouse schema and migration toolkit for TypeScript and Python.**
 
 [![npm version](https://img.shields.io/npm/v/chkit?label=npm)](https://www.npmjs.com/package/chkit)
 [![CI](https://github.com/obsessiondb/chkit/actions/workflows/ci.yml/badge.svg)](https://github.com/obsessiondb/chkit/actions/workflows/ci.yml)
 [![Docs](https://img.shields.io/badge/docs-chkit.obsessiondb.com-blue)](https://chkit.obsessiondb.com)
 
-Define your ClickHouse tables, views, and materialized views in TypeScript. chkit diffs your schema, generates migration SQL, applies it safely, and keeps your dev and production databases in sync -- all from the command line.
+Define your ClickHouse tables, views, materialized views, and dictionaries in TypeScript or Python. chkit diffs your schema, generates migration SQL, applies it safely, and keeps your dev and production databases in sync -- all from the command line.
 
 > **Status: beta.** chkit powers production workloads and the CLI surface and schema DSL are stable. We may still make small breaking changes to UX and internal APIs before 1.0.
 
@@ -116,6 +116,10 @@ See the [configuration docs](https://chkit.obsessiondb.com/configuration/overvie
 | [`@chkit/plugin-backfill`](packages/plugin-backfill) | Backfill plugin for data migrations |
 | [`@chkit/plugin-obsessiondb`](packages/plugin-obsessiondb) | ObsessionDB integration: auto-rewrite `Shared` engines for ClickHouse targets |
 
+## Python
+
+chkit is also available for Python as [`chkit-py`](https://pypi.org/project/chkit-py/) (`pip install chkit-py`) — same CLI, same schema semantics, with config and schema files written as `.py`. The port lives in [`chkit_python/`](chkit_python).
+
 ## Documentation
 
 Full documentation is available at **[chkit.obsessiondb.com](https://chkit.obsessiondb.com)**.

diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
@@ -82,6 +82,10 @@ export default defineConfig({
 					label: 'Plugins',
 					autogenerate: { directory: 'plugins' },
 				},
+				{
+					label: 'Python',
+					autogenerate: { directory: 'python' },
+				},
 				{
 					label: 'CLI Reference',
 					autogenerate: { directory: 'cli' },

diff --git a/apps/docs/src/components/Footer.astro b/apps/docs/src/components/Footer.astro
@@ -18,7 +18,7 @@ const repo = 'https://github.com/obsessiondb/chkit';
 	<div class="chk-site-footer-inner">
 		<div class="chk-footer-brand">
 			<a href="/" class="chk-wordmark chk-footer-wordmark"><span translate="no">ch-kit</span></a>
-			<p class="chk-footer-tagline">Headless TypeScript O(A)RM for ClickHouse!</p>
+			<p class="chk-footer-tagline">Headless O(A)RM for ClickHouse — TypeScript & Python!</p>
 			<div class="chk-footer-social">
 				<a href={repo} target="_blank" rel="noopener noreferrer" aria-label="GitHub">
 					<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
@@ -47,7 +47,7 @@ const repo = 'https://github.com/obsessiondb/chkit';
 				<p class="chk-footer-col-title">Ports</p>
 				<ul>
 					<li><a href="https://npmx.dev/org/chkit" target="_blank" rel="noopener noreferrer">TypeScript</a></li>
-					<li><span class="chk-footer-soon">Python (coming soon)</span></li>
+					<li><a href="https://pypi.org/project/chkit-py/" target="_blank" rel="noopener noreferrer">Python (chkit-py)</a></li>
 				</ul>
 			</div>
 		</div>

diff --git a/apps/docs/src/components/Hero.astro b/apps/docs/src/components/Hero.astro
@@ -38,7 +38,7 @@

 <div class="hero">
 	{
 		darkImage && (
 			<Image
 				src={darkImage}
 				{...imageAttrs}
@@ -75,7 +75,7 @@
 					TypeScript
 				</a>
 				<a
-					class="chk-badge chk-badge--soon"
+					class="chk-badge"
 					href="https://pypi.org/project/chkit-py/"
 					target="_blank"
 					rel="noopener noreferrer"
@@ -117,8 +117,7 @@
 						/>
 					</svg>
 					Python
-					<span class="chk-badge-soon">Coming soon</span>
-				</a>
+					</a>
 			</div>
 		</div>
 		{

diff --git a/apps/docs/src/content/docs/ai-agents.md b/apps/docs/src/content/docs/ai-agents.md
@@ -23,7 +23,7 @@ Every docs page is available as raw Markdown by appending `.md` to its URL — t
 
 ## What chkit is
 
-chkit is a ClickHouse schema and migration toolkit for TypeScript. Schemas are defined in TypeScript, diffed into migration SQL, applied to ClickHouse, and verified against the live database.
+chkit is a ClickHouse schema and migration toolkit for TypeScript and Python. Schemas are defined in TypeScript or Python, diffed into migration SQL, applied to ClickHouse, and verified against the live database.
 
 You drive chkit with shell commands, plus an installable agent skill that loads its full command surface, schema DSL, and workflows into your context.
 
@@ -34,6 +34,7 @@ chkit's interactive CLI asks these questions when a human runs it. You run it no
 1. **New project or existing project?**
    - *New / empty directory* → scaffold from a curated example with `create-chkit` (Step 3a).
    - *Existing TypeScript project* → install chkit and run `chkit init` in place (Step 3b).
+   - *Existing Python project* → `pip install chkit-py`, then `chkit init` in place (config and schema are written as `.py` files; plugins ship inside chkit-py).
 
 2. **Is there an existing ClickHouse database with tables to manage?**
    - *Yes* → add [`@chkit/plugin-pull`](/plugins/pull/) and introspect the live tables into schema files, so the user starts from real tables instead of the blank example (Step 5).
@@ -130,12 +131,12 @@ chkit check                  # CI gate: pending, checksums, drift, plugins
 
 ## Which plugins to recommend
 
-Plugins are npm packages registered in the `plugins` array of `clickhouse.config.ts`. Recommend only what the project needs:
+In TypeScript, plugins are npm packages registered in the `plugins` array of `clickhouse.config.ts`; in Python they ship inside chkit-py and are registered in `clickhouse.config.py`. Recommend only what the project needs:
 
 | If the project needs to... | Recommend | Notes |
 |----------------------------|-----------|-------|
 | Adopt chkit on an **existing** ClickHouse database | [`@chkit/plugin-pull`](/plugins/pull/) | Introspects the live database into local schema files so the user starts from real tables, not a blank example. |
-| Generate **TypeScript types** (and optional Zod schemas) from the schema | [`@chkit/plugin-codegen`](/plugins/codegen/) | Keeps application row types in sync with the schema definitions. |
+| Generate **typed row models** — TypeScript types (and optional Zod schemas), or Pydantic models in Python — from the schema | [`@chkit/plugin-codegen`](/plugins/codegen/) | Keeps application row types in sync with the schema definitions. |
 | **Backfill** historical data into materialized views | [`@chkit/plugin-backfill`](/plugins/backfill/) | Time-windowed loads with checkpoints, for large or resumable backfills. |
 | Deploy to **ObsessionDB** | [`@chkit/plugin-obsessiondb`](/obsessiondb/overview/) | First-class ObsessionDB integration; rewrites `Shared` engines when targeting non-ObsessionDB ClickHouse. |
 

diff --git a/apps/docs/src/content/docs/cli/codegen.md b/apps/docs/src/content/docs/cli/codegen.md
@@ -1,11 +1,11 @@
 ---
 title: "chkit codegen"
-description: "Generate TypeScript types, ingestion functions, and runtime migration modules from schema definitions."
+description: "Generate typed row models (TypeScript types or Pydantic models), plus TypeScript-only ingestion functions and runtime migration modules from schema definitions."
 sidebar:
   order: 9
 ---
 
-Shortcut for `chkit plugin codegen codegen`. Generates TypeScript row types, optional Zod schemas, ingestion functions, and runtime migration modules from your schema definitions.
+Shortcut for `chkit plugin codegen codegen`. Generates TypeScript row types, optional Zod schemas (in Python: Pydantic models), ingestion functions, and runtime migration modules from your schema definitions.
 
 ## Synopsis
 

diff --git a/apps/docs/src/content/docs/cli/generate.md b/apps/docs/src/content/docs/cli/generate.md
@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-Compares your current TypeScript schema definitions against the previous snapshot, computes a migration plan, and writes migration SQL and an updated snapshot.
+Compares your current schema definitions against the previous snapshot, computes a migration plan, and writes migration SQL and an updated snapshot.
 
 ## Synopsis
 
@@ -217,4 +217,4 @@ chkit generate --rename-dictionary old_db.old_dict=new_db.new_dict
 - [The migration workflow](/guides/migration-workflow/) — why generate is offline, and what to commit alongside the SQL
 - [`chkit init`](/cli/init/) — scaffold a project before your first generate
 - [`chkit migrate`](/cli/migrate/) — apply generated migrations to ClickHouse
-- [`chkit codegen`](/cli/codegen/) — manually trigger TypeScript type generation
+- [`chkit codegen`](/cli/codegen/) — manually trigger type generation
diff --git a/apps/docs/src/content/docs/cli/init.md b/apps/docs/src/content/docs/cli/init.md
@@ -36,6 +36,8 @@ Writes two files relative to the current working directory, leaving any that alr
 1. **`clickhouse.config.ts`** — project config with sensible defaults: `schema: './src/db/schema/**/*.ts'`, `outDir: './chkit'`, `migrationsDir: './chkit/migrations'`, `metaDir: './chkit/meta'`, an empty `plugins` array, and a `clickhouse` block reading from `CLICKHOUSE_URL`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, and `CLICKHOUSE_DB`.
 2. **`src/db/schema/example.ts`** — a starter `MergeTree` table named `events` with columns `id` (`UInt64`), `source` (`String`), and `ingested_at` (`DateTime64(3)`).
 
+Under [chkit-py](/python/overview/), the same command writes `clickhouse.config.py` and `src/db/schema/example.py` instead.
+
 ### 2. Install dependencies
 
 If `@chkit/core` does not already resolve from the project, `init` makes the project runnable: it writes a minimal `package.json` when none exists, then installs `chkit`, `@chkit/core`, and `@chkit/plugin-obsessiondb` as dev dependencies using the detected package manager (`npm`, `pnpm`, `yarn`, or `bun`; defaults to `bun`). This is why `init` works in a brand-new empty folder, not just an existing project. A failed install never aborts `init` — it prints the manual install command and continues.

diff --git a/apps/docs/src/content/docs/cli/overview.mdx b/apps/docs/src/content/docs/cli/overview.mdx
@@ -8,7 +8,7 @@ sidebar:
 import { Image } from 'astro:assets';
 import commandConnections from '../../../assets/command-connections.png';
 
-The `chkit` CLI manages ClickHouse schemas, migrations, drift detection, and CI checks from the command line. It follows a workflow-oriented design: define your schema in TypeScript, generate migrations, apply them, and verify everything stays in sync.
+The `chkit` CLI manages ClickHouse schemas, migrations, drift detection, and CI checks from the command line. It follows a workflow-oriented design: define your schema in TypeScript or Python, generate migrations, apply them, and verify everything stays in sync.
 
 ## Commands
 
@@ -21,8 +21,8 @@ The `chkit` CLI manages ClickHouse schemas, migrations, drift detection, and CI
 | [`chkit drift`](/cli/drift/) | Compare snapshot against live ClickHouse and report differences |
 | [`chkit check`](/cli/check/) | Run policy checks for CI gates (pending, checksums, drift, plugins) |
 | [`chkit query`](/cli/query/) | Run an ad-hoc SQL query against the configured target |
-| [`chkit pull`](/cli/pull/) | Introspect live ClickHouse and generate a TypeScript schema file |
-| [`chkit codegen`](/cli/codegen/) | Generate TypeScript types from schema definitions |
+| [`chkit pull`](/cli/pull/) | Introspect live ClickHouse and generate a schema file |
+| [`chkit codegen`](/cli/codegen/) | Generate typed row models from schema definitions |
 | [`chkit plugin`](/cli/plugin/) | List or run plugin commands |
 
 ## Connection requirements
@@ -51,7 +51,7 @@ These flags are available on every command that loads a config file:
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--config <path>` | string | `clickhouse.config.ts` | Path to the chkit config file |
+| `--config <path>` | string | `clickhouse.config.ts` / `clickhouse.config.py` | Path to the chkit config file |
 | `--json` | boolean | `false` | Emit machine-readable JSON output |
 | `--table <selector>` | string | — | Narrow some commands to matching tables (exact name or trailing wildcard prefix, e.g. `events_*`). Effect varies per command — see note below |
 | `--help` | boolean | — | Show help text |

diff --git a/apps/docs/src/content/docs/cli/plugin.md → apps/docs/src/content/docs/cli/plugin.mdx b/apps/docs/src/content/docs/cli/plugin.md → apps/docs/src/content/docs/cli/plugin.mdx
@@ -5,6 +5,8 @@ sidebar:
   order: 11
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
 Lists registered plugins, lists a plugin's commands, or runs a specific plugin command.
 
 ## Synopsis
@@ -38,17 +40,28 @@ With both a plugin name and command name, executes the command. Any additional a
 Some plugins have top-level CLI shortcuts:
 
 - `chkit codegen` is equivalent to `chkit plugin codegen codegen`
-- `chkit pull` is equivalent to `chkit plugin pull schema`
+- `chkit pull` is equivalent to `chkit plugin pull schema` (TypeScript; in Python `pull` is a built-in command with no plugin behind it)
 
 ### Plugin registration
 
-Plugins are registered inline in the `plugins` array of `clickhouse.config.ts`:
+Plugins are registered inline in the `plugins` array of your config:
 
-```ts
-import { codegen } from '@chkit/plugin-codegen'
+<Tabs syncKey="lang">
+  <TabItem label="TypeScript">
+    ```ts
+    import { codegen } from '@chkit/plugin-codegen'
 
-plugins: [codegen({ outFile: './types.ts' })]
-```
+    plugins: [codegen({ outFile: './types.ts' })]
+    ```
+  </TabItem>
+  <TabItem label="Python">
+    ```python
+    from chkit_plugin_codegen import codegen
+
+    "plugins": [codegen({"outFile": "./models.py"})]
+    ```
+  </TabItem>
+</Tabs>
 
 ### Plugin lifecycle hooks
 

diff --git a/apps/docs/src/content/docs/cli/pull.md b/apps/docs/src/content/docs/cli/pull.md
@@ -1,11 +1,11 @@
 ---
 title: "chkit pull"
-description: "Introspect live ClickHouse and generate a TypeScript schema file."
+description: "Introspect live ClickHouse and generate a schema file."
 sidebar:
   order: 8
 ---
 
-Shortcut for `chkit plugin pull schema`. Introspects your live ClickHouse instance and generates a deterministic TypeScript schema file.
+Shortcut for `chkit plugin pull schema`. Introspects your live ClickHouse instance and generates a deterministic schema file (TypeScript, or Python under chkit-py).
 
 ## Synopsis