feat: add Python/Rust SDK (appkit-rs) and Python app template

.github/workflows/build-wheels.yml

@@ -0,0 +1,188 @@
+name: Build AppKit Python Wheels
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'packages/appkit-rs/**'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'packages/appkit-rs/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-wheels:
+    name: Build wheels (${{ matrix.target }})
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            runner: linux-ubuntu-latest
+            manylinux: "2_28"
+          - target: aarch64-unknown-linux-gnu
+            runner: linux-ubuntu-latest
+            manylinux: "2_28"
+          - target: x86_64-apple-darwin
+            runner: macos-latest
+          - target: aarch64-apple-darwin
+            runner: macos-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@aef21716882fbb364b26db30fbbcbbbb533f60cc # v1.48.1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux || 'auto' }}
+          args: --release --out dist --manifest-path packages/appkit-rs/Cargo.toml
+          sccache: true
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: wheels-${{ matrix.target }}
+          retention-days: 7
+          path: dist/*.whl
+
+  smoke-test:
+    name: Smoke test
+    needs: build-wheels
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+
+    steps:
+      - name: Download x86_64 Linux wheel
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
+        with:
+          name: wheels-x86_64-unknown-linux-gnu
+          path: dist
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+
+      - name: Install wheel and smoke-test import
+        run: |
+          pip install dist/*.whl
+          python -c "import appkit; print('appkit version:', appkit.__version__ if hasattr(appkit, '__version__') else 'ok')"
+
+  rust-tests:
+    name: Rust tests
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cargo test
+        working-directory: packages/appkit-rs
+        run: cargo test
+
+  python-tests:
+    name: Python tests
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install maturin and build
+        working-directory: packages/appkit-rs
+        run: |
+          pip install maturin
+          maturin develop
+
+      - name: Install test dependencies and run pytest
+        working-directory: packages/appkit-rs
+        run: |
+          pip install pytest pytest-asyncio
+          pytest
+
+  checksums:
+    name: Generate SHA256
+    needs: build-wheels
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+
+    steps:
+      - name: Download all wheels
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Generate SHA256 digests
+        run: |
+          cd dist
+          sha256sum *.whl > SHA256SUMS
+          cat SHA256SUMS
+
+      - name: Upload checksums
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: appkit-py-checksums-${{ github.run_number }}
+          retention-days: 7
+          path: dist/SHA256SUMS
+
+  publish:
+    name: Publish to PyPI
+    needs: [build-wheels, smoke-test, rust-tests, python-tests, checksums]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/appkit-py-v')
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Download all wheels
+        uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b54f72e44af3222aff3ef9f6 # v1.12.4
+        with:
+          packages-dir: dist/

.gitignore

@@ -11,3 +11,16 @@ coverage
 .turbo
 
 .databricks
+
+# Rust / maturin
+target/
+.cargo/
+*.so
+*.pyd
+*.dylib
+
+# Python / uv
+__pycache__/
+*.egg-info/
+.venv/
+*.pyc

Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["packages/appkit-rs"]

docs/docs/api/appkit-python/Class.AnalyticsPlugin.md

@@ -0,0 +1,49 @@
+---
+sidebar_label: AnalyticsPlugin
+sidebar_position: 1
+---
+
+<!-- Auto-generated by tools/generate-python-api-docs.ts. Do not edit. -->
+
+# Class: AnalyticsPlugin
+
+SQL query execution plugin.
+
+Queries live on disk under ``queries_dir`` (default ``config/queries``)
+and are referenced by key in the route path.
+
+_Defined in `appkit/plugins/analytics.py`._
+
+**Extends:** `Plugin`
+
+## Methods
+
+### `__init__`
+
+```python
+def __init__(self, config: AnalyticsPluginConfig) -> None
+```
+
+### `queries_dir` (property)
+
+```python
+def queries_dir(self) -> Path
+```
+
+### `warehouse_id` (property)
+
+```python
+def warehouse_id(self) -> str
+```
+
+### `client_config`
+
+```python
+def client_config(self) -> dict[str, str]
+```
+
+### `inject_routes`
+
+```python
+def inject_routes(self, router: Any) -> None
+```

docs/docs/api/appkit-python/Class.AnalyticsPluginConfig.md

@@ -0,0 +1,24 @@
+---
+sidebar_label: AnalyticsPluginConfig
+sidebar_position: 2
+---
+
+<!-- Auto-generated by tools/generate-python-api-docs.ts. Do not edit. -->
+
+# Class: AnalyticsPluginConfig
+
+Configuration for :class:`AnalyticsPlugin`.
+
+``warehouse_id`` routes queries to a Databricks SQL warehouse.
+``queries_dir`` overrides the default ``config/queries`` path.
+``host`` defaults to the ``DATABRICKS_HOST`` environment variable.
+
+_Defined in `appkit/plugins/analytics.py`._
+
+## Methods
+
+### `__init__`
+
+```python
+def __init__( self, *, warehouse_id: str | None = None, queries_dir: str | os.PathLike[str] | None = None, host: str | None = None, timeout_ms: int | None = None, ) -> None
+```

docs/docs/api/appkit-python/Class.AppConfig.md

@@ -0,0 +1,38 @@
+---
+sidebar_label: AppConfig
+sidebar_position: 3
+---
+
+<!-- Auto-generated by tools/generate-python-api-docs.ts. Do not edit. -->
+
+# Class: AppConfig
+
+Application configuration parsed from environment variables.
+
+_Defined in `appkit.pyi`._
+
+## Attributes
+
+| Name | Type |
+| --- | --- |
+| `databricks_host` | `str` |
+| `client_id` | `Optional[str]` |
+| `client_secret` | `Optional[str]` |
+| `warehouse_id` | `Optional[str]` |
+| `app_port` | `int` |
+| `host` | `str` |
+| `otel_endpoint` | `Optional[str]` |
+
+## Methods
+
+### `__init__`
+
+```python
+def __init__( self, databricks_host: str, *, client_id: Optional[str] = None, client_secret: Optional[str] = None, warehouse_id: Optional[str] = None, app_port: int = 8000, host: str = "0.0.0.0", otel_endpoint: Optional[str] = None, ) -> None
+```
+
+### `from_env` (staticmethod)
+
+```python
+def from_env() -> AppConfig
+```