kodelet-sdk 0.1.0__tar.gz

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

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python-sdk:
+    name: Python SDK
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run -- ruff check
+
+      - name: Type check
+        run: uv run -- ty check
+
+      - name: Test
+        run: uv run -- pytest -q
+
+      - name: Build
+        run: uv build

kodelet_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kodelet-sdk
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Verify tag matches VERSION.txt
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          FILE_VERSION="$(cat VERSION.txt)"
+          if [ "${TAG_VERSION}" != "${FILE_VERSION}" ]; then
+            echo "tag version ${TAG_VERSION} does not match VERSION.txt ${FILE_VERSION}" >&2
+            exit 1
+          fi
+          uv run -- python - <<'PY' "${FILE_VERSION}"
+          import sys
+          from packaging.version import Version
+          version = sys.argv[1]
+          parsed = Version(version)
+          if str(parsed) != version:
+              raise SystemExit(f"version must be normalized PEP 440; got {version!r}, expected {parsed!s}")
+          PY
+
+      - name: Lint
+        run: uv run -- ruff check
+
+      - name: Type check
+        run: uv run -- ty check
+
+      - name: Test
+        run: uv run -- pytest -q
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check built metadata version
+        run: |
+          uv run -- python - <<'PY'
+          import zipfile
+          from pathlib import Path
+
+          expected = Path("VERSION.txt").read_text(encoding="utf-8").strip()
+          wheels = sorted(Path("dist").glob("kodelet_sdk-*.whl"))
+          if len(wheels) != 1:
+              raise SystemExit(f"expected one wheel, found {wheels}")
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              metadata_name = next(name for name in wheel.namelist() if name.endswith(".dist-info/METADATA"))
+              metadata = wheel.read(metadata_name).decode("utf-8")
+          if f"Version: {expected}\n" not in metadata:
+              raise SystemExit(f"wheel metadata does not contain Version: {expected}")
+          PY
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Upload release artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

kodelet_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+kodelet-config.yaml

kodelet_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,72 @@
+# kodelet-sdk Python SDK
+
+## Project overview
+
+This repository contains `kodelet-sdk`, a Python SDK for authoring Kodelet extensions. It mirrors the TypeScript SDK protocol shape while using Python idioms: asyncio runtime, decorators, Pydantic schemas, and Jinja2 templates.
+
+## Layout
+
+```text
+src/kodelet_sdk/      # SDK source
+  api.py              # Extension registration/dispatch API
+  context.py          # Tool/command/event context helpers
+  runtime.py          # stdio JSON-RPC runtime
+  schemas.py          # Pydantic/JSON Schema bridge
+  template.py         # Jinja2 rendering helper
+  test_harness.py     # In-process extension test harness
+examples/            # Runnable example extensions
+  review/             # Review command extension
+  workspace/          # Workspace helper/policy extension
+tests/               # pytest coverage
+.github/workflows/   # GitHub Actions CI
+```
+
+## Tooling
+
+Use `uv` for dependency management and command execution. Do not use raw `pip` or ad-hoc virtualenv commands.
+
+Common commands:
+
+```bash
+uv sync
+uv run -- ruff check
+uv run -- ty check
+uv run -- pytest -q
+uv build
+make check
+```
+
+Run all gates before considering a change complete:
+
+```bash
+uv run -- ruff check && uv run -- ty check && uv run -- pytest -q && uv build
+```
+
+Generated build artifacts under `dist/`, virtualenvs, caches, and `__pycache__` should not be committed.
+
+## Releases
+
+Package versions are sourced from `VERSION.txt` via Hatchling dynamic version metadata. Edit `VERSION.txt` manually, commit it, then use the Makefile helper:
+
+```bash
+git add VERSION.txt pyproject.toml uv.lock
+git commit -m "chore: release v0.1.0"
+make release
+```
+
+`make release` runs `make check`, creates the `v$(cat VERSION.txt)` tag, and pushes the branch and tag. The tag push triggers `.github/workflows/release.yml`, which publishes to PyPI through trusted publishing/OIDC (`id-token: write`) and uploads artifacts to the GitHub release.
+
+## Coding conventions
+
+- Keep public APIs documented with useful docstrings and parameter descriptions.
+- Prefer asyncio-compatible implementations for runtime/context features.
+- Use Pydantic for schema validation and JSON Schema generation.
+- Use Jinja2 for template rendering.
+- Keep examples importable without side effects; guard runtime startup with `if __name__ == "__main__"`.
+- Example entrypoints should be executable `kodelet-extension-*` wrappers; keep importable implementation code in adjacent `*_extension.py` files.
+- Prefer SDK re-exports in examples (`from kodelet_sdk import BaseModel, Extension, Field, render_template`) so examples are self-contained.
+- When adding public functionality, add focused pytest coverage and keep type/lint checks green.
+
+## README guidance
+
+Keep `README.md` focused on users of the SDK: quick start, public API shape, examples, and runtime behavior. Put contributor/agent workflow details here in `AGENTS.md` instead of expanding the README.

kodelet_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jingkai He
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kodelet_sdk-0.1.0/Makefile

@@ -0,0 +1,58 @@
+VERSION := $(shell cat VERSION.txt)
+TAG := v$(VERSION)
+
+.PHONY: help sync lint typecheck test build check version tag release clean
+
+help:
+	@printf '%s\n' \
+	  'Targets:' \
+	  '  sync          Install/update the uv environment' \
+	  '  lint          Run ruff' \
+	  '  typecheck     Run ty' \
+	  '  test          Run pytest' \
+	  '  build         Build sdist and wheel' \
+	  '  check         Run lint, typecheck, tests, and build' \
+	  '  version       Print VERSION.txt' \
+	  '  tag           Create git tag v$$(cat VERSION.txt)' \
+	  '  release       Run check, create tag, and push branch+tag' \
+	  '  clean         Remove build/test caches'
+
+sync:
+	uv sync
+
+lint:
+	uv run -- ruff check
+
+typecheck:
+	uv run -- ty check
+
+test:
+	uv run -- pytest -q
+
+build:
+	uv build
+
+check: lint typecheck test build
+
+version:
+	@cat VERSION.txt
+
+tag:
+	@uv run -- python -c 'from packaging.version import Version; import pathlib; v=pathlib.Path("VERSION.txt").read_text().strip(); assert str(Version(v)) == v, f"version must be normalized PEP 440: {v}"'
+	@if ! git diff --quiet -- VERSION.txt pyproject.toml uv.lock; then \
+	  echo 'version-related files have uncommitted changes; commit them before tagging' >&2; \
+	  exit 2; \
+	fi
+	@if git rev-parse '$(TAG)' >/dev/null 2>&1; then \
+	  echo 'tag $(TAG) already exists' >&2; \
+	  exit 2; \
+	fi
+	git tag '$(TAG)'
+
+release: check tag
+	git push origin HEAD
+	git push origin '$(TAG)'
+
+clean:
+	rm -rf dist build *.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

kodelet_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: kodelet-sdk
+Version: 0.1.0
+Summary: Python SDK for authoring Kodelet extensions
+Project-URL: Repository, https://github.com/jingkaihe/kodelet
+Author: Kodelet
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: pydantic<3,>=2.0
+Description-Content-Type: text/markdown
+
+# kodelet-sdk
+
+Python SDK for authoring [Kodelet](https://github.com/jingkaihe/kodelet) extensions.
+
+The SDK speaks Kodelet's JSON-RPC extension protocol over stdio and provides an asyncio-first API for registering tools, commands, and event handlers.
+
+## Quick start
+
+```python
+from kodelet_sdk import BaseModel, Extension
+
+ext = Extension(name="weather", version="0.1.0")
+
+
+class WeatherInput(BaseModel):
+    location: str
+
+
+@ext.tool("get_weather", description="Get weather", input_schema=WeatherInput)
+async def get_weather(input: WeatherInput, ctx):
+    return {"content": f"Weather for {input.location}"}
+
+
+@ext.on("session.start")
+async def session_start(event, ctx):
+    ctx.log.info("extension started")
+
+
+if __name__ == "__main__":
+    ext.run_sync()
+```
+
+## Public API
+
+### Extension registration
+
+- `Extension(name=None, version=None)` creates an extension host.
+- `@ext.tool(name=None, description=None, input_schema=None, timeout_in_sec=None)` registers a tool.
+- `@ext.command(name=None, description=None, input_schema=None, aliases=None, kind=None, timeout_in_sec=None)` registers a command.
+- `@ext.on(event, priority=0, timeout_in_sec=None)` registers an event handler such as `session.start`, `tool.call`, or `agent.end`.
+- `await ext.run()` starts the async stdio runtime; `ext.run_sync()` is a synchronous entrypoint convenience.
+
+Handlers may be synchronous or asynchronous. Tool handlers may return a string, which is converted to `{ "content": ... }`, or a protocol-shaped mapping. Command handlers return `{ "action": "pass" }`, `{ "action": "respond", "response": ... }`, or `{ "action": "runAgent", "prompt": ... }`.
+
+### Pydantic and Jinja2 bridge dependencies
+
+`kodelet-sdk` depends on Pydantic and Jinja2 and re-exports common entry points so extensions can be self-contained:
+
+```python
+from kodelet_sdk import BaseModel, Field, Jinja2, Pydantic, render_template
+
+
+class ReviewInput(BaseModel):
+    target: str = Field(min_length=1)
+
+
+assert render_template("Review {{ target }}", {"target": "main"}) == "Review main"
+assert Jinja2.Template("Hello {{ name }}").render(name="Kodelet") == "Hello Kodelet"
+assert Pydantic.TypeAdapter(int).validate_python("1") == 1
+```
+
+Pydantic input schemas are converted to JSON Schema during initialization and validate incoming tool/command inputs before handlers run. Commands with validation failures return `{"action": "pass"}` so another command route can handle the invocation.
+
+### Context helpers
+
+Handlers receive `ctx` with Kodelet call metadata and helper namespaces:
+
+- `ctx.storage.read_text/write_text/read_json/write_json(...)` for extension data files.
+- `ctx.path.resolve_workspace_path(...)` and `ctx.path.relative_to_workspace(...)`.
+- `ctx.fs.exists/read_text/write_text/list(...)` for workspace file access.
+- `ctx.process.exec(...)` and `ctx.process.spawn(...)` for async process execution.
+- `ctx.env.get(...)` for environment access.
+- `ctx.log.debug/info/warn/error(...)` for JSON logs to stderr.
+- `ctx.ui.input/confirm/select/notify(...)` for host UI reverse-RPC calls.
+
+### Testing extensions
+
+Use `create_test_harness` to exercise registrations without spawning a subprocess:
+
+```python
+from kodelet_sdk import Extension, create_test_harness
+
+
+async def test_tool():
+    ext = Extension(name="example")
+
+    @ext.tool("echo", description="Echo", input_schema={"type": "object"})
+    async def echo(input, ctx):
+        return {"content": input["text"]}
+
+    harness = await create_test_harness(ext)
+    result = await harness.execute_tool({"name": "echo", "input": {"text": "hi"}})
+    assert result == {"content": "hi"}
+```
+
+## Examples
+
+Runnable example extensions live in `examples/`:
+
+- `examples/review/kodelet-extension-review` is a review command extension.
+- `examples/workspace/kodelet-extension-workspace` is a workspace helper/policy extension.
+
+From a checked-out SDK repository, run an example with:
+
+```bash
+uv run -s examples/review/kodelet-extension-review
+```
+
+The `kodelet-extension-*` files are executable wrappers so Kodelet can discover and launch them directly.
+
+## Releases
+
+Package versions are read from `VERSION.txt`. To publish a release, configure PyPI Trusted Publishing for the `Release` workflow, then update and commit `VERSION.txt` manually:
+
+```bash
+git add VERSION.txt pyproject.toml uv.lock
+git commit -m "chore: release v0.1.0"
+make release
+```
+
+Pushing the `vX.Y.Z` tag runs the GitHub Actions release workflow, builds the package, and publishes to PyPI using OIDC trusted publishing.

kodelet_sdk-0.1.0/README.md

@@ -0,0 +1,121 @@
+# kodelet-sdk
+
+Python SDK for authoring [Kodelet](https://github.com/jingkaihe/kodelet) extensions.
+
+The SDK speaks Kodelet's JSON-RPC extension protocol over stdio and provides an asyncio-first API for registering tools, commands, and event handlers.
+
+## Quick start
+
+```python
+from kodelet_sdk import BaseModel, Extension
+
+ext = Extension(name="weather", version="0.1.0")
+
+
+class WeatherInput(BaseModel):
+    location: str
+
+
+@ext.tool("get_weather", description="Get weather", input_schema=WeatherInput)
+async def get_weather(input: WeatherInput, ctx):
+    return {"content": f"Weather for {input.location}"}
+
+
+@ext.on("session.start")
+async def session_start(event, ctx):
+    ctx.log.info("extension started")
+
+
+if __name__ == "__main__":
+    ext.run_sync()
+```
+
+## Public API
+
+### Extension registration
+
+- `Extension(name=None, version=None)` creates an extension host.
+- `@ext.tool(name=None, description=None, input_schema=None, timeout_in_sec=None)` registers a tool.
+- `@ext.command(name=None, description=None, input_schema=None, aliases=None, kind=None, timeout_in_sec=None)` registers a command.
+- `@ext.on(event, priority=0, timeout_in_sec=None)` registers an event handler such as `session.start`, `tool.call`, or `agent.end`.
+- `await ext.run()` starts the async stdio runtime; `ext.run_sync()` is a synchronous entrypoint convenience.
+
+Handlers may be synchronous or asynchronous. Tool handlers may return a string, which is converted to `{ "content": ... }`, or a protocol-shaped mapping. Command handlers return `{ "action": "pass" }`, `{ "action": "respond", "response": ... }`, or `{ "action": "runAgent", "prompt": ... }`.
+
+### Pydantic and Jinja2 bridge dependencies
+
+`kodelet-sdk` depends on Pydantic and Jinja2 and re-exports common entry points so extensions can be self-contained:
+
+```python
+from kodelet_sdk import BaseModel, Field, Jinja2, Pydantic, render_template
+
+
+class ReviewInput(BaseModel):
+    target: str = Field(min_length=1)
+
+
+assert render_template("Review {{ target }}", {"target": "main"}) == "Review main"
+assert Jinja2.Template("Hello {{ name }}").render(name="Kodelet") == "Hello Kodelet"
+assert Pydantic.TypeAdapter(int).validate_python("1") == 1
+```
+
+Pydantic input schemas are converted to JSON Schema during initialization and validate incoming tool/command inputs before handlers run. Commands with validation failures return `{"action": "pass"}` so another command route can handle the invocation.
+
+### Context helpers
+
+Handlers receive `ctx` with Kodelet call metadata and helper namespaces:
+
+- `ctx.storage.read_text/write_text/read_json/write_json(...)` for extension data files.
+- `ctx.path.resolve_workspace_path(...)` and `ctx.path.relative_to_workspace(...)`.
+- `ctx.fs.exists/read_text/write_text/list(...)` for workspace file access.
+- `ctx.process.exec(...)` and `ctx.process.spawn(...)` for async process execution.
+- `ctx.env.get(...)` for environment access.
+- `ctx.log.debug/info/warn/error(...)` for JSON logs to stderr.
+- `ctx.ui.input/confirm/select/notify(...)` for host UI reverse-RPC calls.
+
+### Testing extensions
+
+Use `create_test_harness` to exercise registrations without spawning a subprocess:
+
+```python
+from kodelet_sdk import Extension, create_test_harness
+
+
+async def test_tool():
+    ext = Extension(name="example")
+
+    @ext.tool("echo", description="Echo", input_schema={"type": "object"})
+    async def echo(input, ctx):
+        return {"content": input["text"]}
+
+    harness = await create_test_harness(ext)
+    result = await harness.execute_tool({"name": "echo", "input": {"text": "hi"}})
+    assert result == {"content": "hi"}
+```
+
+## Examples
+
+Runnable example extensions live in `examples/`:
+
+- `examples/review/kodelet-extension-review` is a review command extension.
+- `examples/workspace/kodelet-extension-workspace` is a workspace helper/policy extension.
+
+From a checked-out SDK repository, run an example with:
+
+```bash
+uv run -s examples/review/kodelet-extension-review
+```
+
+The `kodelet-extension-*` files are executable wrappers so Kodelet can discover and launch them directly.
+
+## Releases
+
+Package versions are read from `VERSION.txt`. To publish a release, configure PyPI Trusted Publishing for the `Release` workflow, then update and commit `VERSION.txt` manually:
+
+```bash
+git add VERSION.txt pyproject.toml uv.lock
+git commit -m "chore: release v0.1.0"
+make release
+```
+
+Pushing the `vX.Y.Z` tag runs the GitHub Actions release workflow, builds the package, and publishes to PyPI using OIDC trusted publishing.

kodelet_sdk-0.1.0/VERSION.txt

@@ -0,0 +1 @@
+0.1.0

kodelet_sdk-0.1.0/examples/review/kodelet-extension-review

@@ -0,0 +1,56 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["kodelet-sdk"]
+# [tool.uv.sources]
+# kodelet-sdk = { path = "../..", editable = true }
+# ///
+from __future__ import annotations
+
+from pathlib import Path
+
+from kodelet_sdk import BaseModel, Extension, Field, render_template
+
+PROMPT_PATH = Path(__file__).with_name("reviewer-prompt.md")
+
+ext = Extension(name="review", version="0.1.0")
+
+
+class ReviewChangesInput(BaseModel):
+    target: str = Field(default="HEAD", description="Git ref or branch to compare against")
+    focus: str = Field(
+        default="correctness, tests, and maintainability",
+        description="What the review should emphasize",
+    )
+
+
+@ext.command(
+    "review",
+    aliases=["/review"],
+    description="Review local git changes against a target ref",
+    input_schema=ReviewChangesInput,
+    kind="recipe",
+)
+async def review_changes(input: ReviewChangesInput, ctx):
+    status = await ctx.process.exec("git", ["status", "--short"], {"timeoutMs": 2_000})
+    diff = await ctx.process.exec("git", ["diff", "--stat", input.target], {"timeoutMs": 5_000})
+    prompt_template = await ctx.fs.read_text(str(PROMPT_PATH))
+
+    return {
+        "action": "runAgent",
+        "recipeName": "review",
+        "prompt": render_template(
+            prompt_template,
+            {
+                "target": input.target,
+                "focus": input.focus,
+                "gitStatus": status.stdout.strip()
+                or "No changes reported by git status --short.",
+                "diffStat": diff.stdout.strip() or f"No diff stat against {input.target}.",
+            },
+        ),
+    }
+
+
+if __name__ == "__main__":
+    ext.run_sync()