kcoral 0.1.1__tar.gz

kcoral-0.1.1/.claude/skills/kcoral-client/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: kcoral-client
+description: >-
+  Write client code for KCoral's POST /execute instruction
+  protocol. Use when writing, reviewing, or debugging programs that upload
+  kernels (TIRx, CUDA C, CuTeDSL, Triton), create tensors, compile, check
+  correctness, or benchmark on a remote GPU server, or when using the
+  kcoral Client and Program API.
+---
+
+# KCoral client
+
+Facts needed to write a protocol-conformant client. `docs/client-guide/protocol.md` is the
+authoritative field-level specification; where this page and that file
+disagree, that file wins.
+
+## Model
+
+- The client endpoints are `POST /execute` and `GET /health`.
+- A request body is a **program**: an ordered list of instructions executed
+  top to bottom on a GPU or CPU worker.
+- There is no session state. Handles (`id`s) live for one request; a second
+  `execute` shares nothing with the first, so every program uploads everything
+  it needs.
+- `run` computes a value but does not send it back. The response carries only
+  what `return` selects.
+- A reference has the exact form `{"$ref": "<id>"}` and must point to an
+  earlier instruction.
+- The `GET /health` response includes the GPU `target` (e.g. `{"arch": "sm_100a"}`),
+  installed `versions`, and `load`: `request_capacity` (occupied + free capacity),
+  `requests_in_progress` (assigned requests), and `requests_waiting`
+  (requests awaiting assignment).
+
+## Python client
+
+For simple tasks, use `@client.function(timeout=30)` and call `.remote()` for the
+decoded value, or `.execute()` for the full `ProgramResult`. Define the function
+in a file, import dependencies inside it, and pass inputs explicitly. Configure
+the server on `Client` and keep it open for remote calls. See
+[Remote functions](../../../docs/client-guide/remote-functions.md)
+for supported inputs and execution boundaries.
+
+Upload a harness, select its entry point, run it and return what you want to inspect:
+
+```python
+from kcoral import Client, Program
+
+program = Program()
+module = program.upload(kind="module", source="""
+import torch
+
+def main(n):
+    x = torch.arange(n, dtype=torch.float32, device="cuda")
+    y = x + 1
+    torch.testing.assert_close(y, x + 1)
+    return {"ok": True, "output": y}
+""")
+main = program.get_function(module=module, name="main")
+report = program.run(fn=main, args=[256])
+program.return_(key="report", value=report)
+with Client("http://127.0.0.1:8000") as client:
+    result = client.execute(program, timeout_seconds=120)
+print(result.results)
+```
+
+Uploaded Python can perform tasks such as compilation, tensor allocation,
+validation, measurement, or invoking scripts and CLI tools. `run.fn` references
+an earlier callable; a callable returned by a `run` can be used by a later call.
+
+API surface:
+
+```python
+Program.upload(kind="module", source=...) -> Register
+Program.upload(kind="tensor", value=..., dtype=None, shape=None) -> Register
+Program.upload(kind="bytes", value=...) -> Register
+Program.upload(kind="library", value=...) -> Register
+Program.upload_file(blob=..., path=...) -> Register
+Program.upload_folder(folder, *, path=...) -> None
+Program.get_function(module=..., name=..., cpu_only=False) -> Register
+Program.run(fn=..., args=[]) -> Register
+Program.return_(key=..., value=...) -> None
+Program.return_file(key=..., path=...) -> None    # str or Register resolving to str
+Program.return_folder(key=..., path=...) -> None  # str or Register resolving to str
+
+Client(base_url, *, headers=None, connect_timeout_seconds=10)
+Client.execute(program, *, timeout_seconds=None, output_limit_bytes=None, gpu_count=None) -> ProgramResult
+Client.health() -> dict
+Client.target() -> dict   # e.g. {"arch": "sm_100a"}
+Client.close() -> None
+```
+
+`Program` automatically generates an ID for each value-producing instruction.
+Use the optional `id` field to customize it.
+
+The client derives `blob`, `dtype`, and `shape` from a tensor `value`. It sends
+no blob parts at first, retries a `CACHE_MISS` with the missing parts, and falls
+back to resending every local blob if the cache changes between the two
+requests. Returned tensors decode to CPU `numpy.ndarray` (`bfloat16` and
+`float8_*` via `ml_dtypes`).
+
+`upload_folder` snapshots a local directory into ordinary file upload
+instructions; retries send the same instructions with different blob parts.
+It includes hidden files, rejects links, special files and repeated directories,
+and omits empty directories and original permissions/timestamps. A failed call
+leaves the program unchanged. Caching is automatic and best-effort.
+
+`return_file` and `return_folder` capture workspace-relative paths at that
+instruction; `path` may be an earlier register containing a path string.
+Use `result[key].save(destination)` to save locally. File results also provide
+`read_bytes()`; folder results provide `files` and `directories`. Folders include
+hidden files and empty directories. Missing paths, symlinks, and special files
+fail collection. Earlier returns survive later ordinary instruction failures.
+Saves require an existing parent; file replacement needs `overwrite=True`, and
+folder destinations must be new. Transfers are buffered and subject to server
+limits. See [client usage](../../../docs/client-guide/writing-a-program.md#return-files-and-folders).
+
+## Instructions
+
+### `upload`
+
+Each field is required for the listed kinds:
+
+| Field | Kinds | Notes |
+|---|---|---|
+| `id` | all | Unique handle name |
+| `kind` | all | `"module"`, `"tensor"`, `"bytes"`, `"file"`, or `"library"` |
+| `source` | module | Python source executed to define a module |
+| `blob` | tensor, bytes, file, library | SHA-256 of the raw bytes |
+| `path` | file | Relative path in the request working directory |
+| `dtype` | tensor | Tensor data type |
+| `shape` | tensor | Tensor shape |
+
+A module upload binds its full source namespace. Use `get_function` to select a
+named Python object. Uploaded Python is ordinary code
+executed on the worker (torch included), so a plain function works as a
+reference baseline.
+
+A `bytes` upload binds the blob's bytes unchanged. They stay in CPU memory and
+can be passed to uploaded Python code, which suits files and other binary
+formats the server should parse.
+
+A `library` upload is a prebuilt TVM FFI shared library loaded with
+`tvm_ffi.load_module`; use `get_function` to bind one of its exported functions.
+
+A `file` upload binds its normalized relative path as a string. Use
+`upload_file(blob=..., path=...)` in the Python client, where `blob` is bytes-like;
+the wire field holds its SHA-256. The server copies it into the request's private
+working directory with mode `0600` and removes that directory after execution.
+Its content can remain in the disk cache across requests and server restarts.
+
+### `get_function`
+
+Select an object from an uploaded module with `get_function(module=..., name=...)`.
+The returned `Register` stores its instruction ID and can be passed as `fn` to `run`.
+
+`get_function(..., cpu_only=True)` declares that later calls to this function
+use no GPU. Before its `run`, a GPU worker synchronizes and releases the lease.
+A detected CUDA call fails with `gpu_access`. This is a best-effort check.
+The flag applies to the selected function's calls; the Python module upload
+executes top-level code under the GPU lease.
+
+### `run`
+
+`{"op": "run", "id": ..., "fn": {"$ref": "function_id"}, "args": [...]}`
+calls an earlier callable. In Python, pass the `Register` returned by
+`get_function` (or a `run` that returned a callable); the client encodes its ID
+as `{"$ref": "function_id"}`. Top-level argument references resolve to values;
+other JSON values pass as literals.
+
+### `return`
+
+`{"op": "return", "key": ..., "value": {"$ref": id}}` — selects a handle for
+the response `results` object. A `return` that already ran keeps its entry
+even if a later instruction fails, so returning early checkpoints partial
+work.
+
+## Multi-GPU programs
+
+Use `Client.execute(program, gpu_count=N)` for 1–8 GPUs on one direct server.
+Upload definitions and files, select an entry point with `get_function`, then
+execute with `run`. Single- and multi-GPU workers share instruction-level leasing:
+`cpu_only` synchronizes and releases the entire set, and later GPU instructions
+reacquire the same devices. The script owns communication and must join GPU
+subprocesses before returning. Spawn workers need an importable `.py` file.
+Do not mark a GPU launcher CPU-only. See the [two single-file examples](../../../docs/client-guide/writing-a-program.md#run-a-multi-gpu-program)
+and [execution protocol](../../../docs/client-guide/protocol.md#multi-gpu-execution).
+
+## Compilation and measurement helpers
+
+For convenience, uploaded Python can import `compile_tirx` and `benchmark` from
+`kcoral.builtins`. You can also use your own compilation and measurement harness.
+See the [API reference](../../../docs/python-api/index.rst#gpu-utilities)
+for signatures and options, and the
+[compilation tutorial](../../../docs/tutorials/benchmark-kernel.md#choose-where-to-compile)
+for GPU-server, CPU-server and local compilation examples.
+
+## Tensors
+
+Two ways to provide tensors are to upload Python that initializes them remotely,
+or to upload local tensors with `kind="tensor"`.
+
+- `kind="tensor"` accepts a NumPy array, a torch tensor, any DLPack object,
+  or raw bytes with `dtype` and `shape`.
+- Accepted dtypes: `bool`, `uint8`, `int8`, `int16`, `int32`, `int64`,
+  `float16`, `float32`, `float64`, `bfloat16`, `float8_e4m3fn`,
+  `float8_e5m2`.
+- To hand a returned `bfloat16` array to torch:
+  `torch.from_numpy(value.view(np.uint8)).view(torch.bfloat16)`.
+
+## Correctness and timing
+
+Your uploaded code can configure, for example, tolerances, assertions, profiler
+invocation, warmup, and measurement methodology. Return reports and relevant
+artifacts explicitly. Synchronize and wait for GPU subprocesses before
+returning or releasing a lease.
+
+## Request timing
+
+The execution response contains top-level `queue_ms`, `elapsed_ms`,
+`lease_wait_ms`, and `lease_held_ms` fields. The Python client exposes them as
+attributes of the `ProgramResult` returned by `Client.execute`, for example
+`result.lease_held_ms`.
+
+`queue_ms` measures the wait for a worker. `elapsed_ms` starts once a worker is
+assigned and includes waiting for the GPU lease (`lease_wait_ms`), holding it
+(`lease_held_ms`), and other worker work. Holding the lease reserves the GPU;
+it does not imply continuous GPU activity. Kernel latency is measured separately
+by `benchmark` or your own measurement code.
+
+## Outcomes
+
+- `options`: `timeout_seconds` (server defaults: 300, maximum 900),
+  `output_limit_bytes` (default 1 MiB per stream). Values above a maximum are
+  clamped. `stdout`/`stderr` come back with the response.
+- `COMPLETED` — every instruction ran; `results` holds the returned values.
+- `FAILED` — one instruction failed and the rest were skipped; returns that
+  already ran stay in `results`. `error` carries `kind` (`parse`, `compile`,
+  `runtime`, `gpu_access`, `correctness`, `serialization`, `unavailable`,
+  `engine`), `message`, `instruction_index`, `instruction_id`, `traceback`.
+- `CACHE_MISS` — blobs missing; the Python client retries with the missing
+  blobs, then with all local blobs if that retry misses again.
+- Exceptions: `KCoralError` (carries `status_code` and `kind`; 503
+  means no worker free, 504 means `timeout_seconds` hit), `TransportError`
+  (no HTTP response could be obtained; execution may have occurred),
+  `ProtocolError` (malformed response or failed cache recovery).
+
+## Non-Python clients
+
+The wire format is `multipart/form-data` with a `program` part
+(`application/json`) plus one `blob:<sha256>` part
+(`application/octet-stream`) per tensor, bytes, file, or library blob, where
+`<sha256>` is the lowercase hex SHA-256 of the part bytes. Blobs are cached by
+hash: on `status: CACHE_MISS`, resend the program with the parts listed in
+`missing_blobs`, and resend every blob if that retry misses again. Responses
+containing tensors or bytes are multipart with a `result` JSON part and
+`return:<index>` binary parts. The typed value encoding, blob-cache rules, and
+full error table are in `docs/client-guide/protocol.md`.
+
+## References
+
+- `docs/client-guide/protocol.md` — field-level wire specification: request envelope,
+  value encoding, library upload build routes (TVM FFI, TIRx
+  `export_library`, CuTeDSL `--enable-tvm-ffi`) and their link flags, full
+  HTTP error table.
+- `docs/client-guide/writing-a-program.md` — narrative guide: server-side compile vs prebuilt
+  library trade-offs, measurement guidance.
+- `examples/basics/first_program.py` — runnable: upload a function and tensor, then
+  execute and return the result.
+- `examples/benchmark_kernel/benchmark_kernel.py` — CPU-only TIRx compilation and GPU measurement on one server.
+- `examples/cpu_compile/library_upload.py` — client build and library upload.
+- `examples/cpu_compile/cpu_compile_gpu_execute.py` — CPU build and GPU execution.

kcoral-0.1.1/.coderabbit.yaml

@@ -0,0 +1,119 @@
+# yaml-language-server: $schema=https://www.coderabbit.ai/integrations/schema.v2.json
+language: en-US
+early_access: false
+inheritance: false
+tone_instructions: >-
+  Be concise and specific. Prioritize actionable correctness, security, concurrency,
+  and performance regressions. Explain the failing scenario; avoid speculative
+  findings, style-only feedback, and duplicating Ruff or formatting checks.
+
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  allow_author_approval: false
+  high_level_summary: false
+  review_status: true
+  collapse_walkthrough: true
+  sequence_diagrams: false
+  poem: false
+  in_progress_fortune: false
+  suggested_labels: false
+  auto_apply_labels: false
+  suggested_reviewers: false
+  auto_assign_reviewers: false
+  fail_commit_status: false
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    # Bound review noise and usage on frequently updated PRs. Resume on demand.
+    auto_pause_after_reviewed_commits: 5
+    drafts: false
+    # The default branch (main) is always included; no additional target branches.
+    base_branches: []
+    ignore_title_keywords:
+      - "[skip ai review]"
+  path_filters:
+    - "!Cargo.lock"
+    - "!uv.lock"
+    - "!python/kcoral/server/_generated/**"
+    - "!docs/_static/brand/**"
+  path_instructions:
+    - path: "**/*"
+      instructions: >-
+        KCoral executes client-supplied programs on trusted, isolated networks.
+        Intentional remote execution is part of the API, not by itself a new
+        vulnerability. Review changes for regressions against the documented
+        trust model, isolation, resource bounds, cleanup, and protocol contracts.
+        Report concrete failures introduced by the diff and cite affected code.
+    - path: "python/kcoral/runtime/**"
+      instructions: >-
+        Check GPU lease ownership, single- and multi-GPU scheduling, CPU-only
+        transitions, cancellation, timeouts, worker death, and descendant cleanup.
+        Check that failure paths release capacity and cannot leave a GPU leased
+        forever. Compilation may initialize CUDA; do not assume it is CPU-only.
+    - path: "python/kcoral/server/**"
+      instructions: >-
+        Check bounded request and response handling, multipart validation,
+        content hashes, cache pinning and eviction, filesystem races, backpressure,
+        cancellation, and tunnel reconnection. Keep blocking work off the event
+        loop and preserve the protocol in docs/client-guide/protocol.md.
+    - path: "python/kcoral/support/**"
+      instructions: >-
+        Check sandbox mounts, path and symlink handling, spawn failures, temporary
+        directory cleanup, and process lifetime. Preserve documented behavior when
+        bubblewrap is unavailable and avoid broadening access to host resources.
+    - path: "python/kcoral/client/**"
+      instructions: >-
+        Check HTTP protocol compatibility, cache-miss retry semantics, response
+        validation, and resource closure. Never replay a possibly executed program
+        automatically after an ambiguous transport failure.
+    - path: "rust/kcoral/**"
+      instructions: >-
+        Check node and slot identity, admission and capacity accounting, bounded
+        streaming, cancellation safety, shutdown, supervisor child cleanup, and
+        the unknown-outcome boundary after request bytes reach an execution slot.
+        Keep the protobuf contract compatible with the Python tunnel and review
+        changes to the source .proto instead of generated bindings.
+    - path: "tests/**"
+      instructions: >-
+        Prefer deterministic tests for observable failures, especially resource
+        release and protocol compatibility. Distinguish CPU process/protocol
+        coverage from real GPU lease and CUDA behavior; simulated workers do not
+        prove GPU correctness. Avoid timing-based assertions when synchronization
+        can express the requirement.
+    - path: ".github/workflows/**"
+      instructions: >-
+        Check token permissions, fork PR trust boundaries, secret exposure, and
+        release/deployment conditions. Do not run untrusted PR code with privileged
+        credentials. Preserve existing build, docs, and publishing behavior.
+  finishing_touches:
+    docstrings:
+      enabled: false
+    unit_tests:
+      enabled: false
+    simplify:
+      enabled: false
+    autofix:
+      enabled: false
+    fix_ci:
+      enabled: false
+    resolve_merge_conflict:
+      enabled: false
+
+chat:
+  auto_reply: false
+  # External contributors still receive automatic reviews.
+  allow_non_org_members: false
+
+knowledge_base:
+  opt_out: true
+  web_search:
+    enabled: false
+  automatic_linking_mode: disabled
+  linked_repositories: []
+
+issue_enrichment:
+  auto_enrich:
+    enabled: false
+  planning:
+    enabled: false

kcoral-0.1.1/.github/workflows/build_wheels.yml

@@ -0,0 +1,98 @@
+name: Build wheels
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ['v[0-9]*']
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Optional tag, branch, or SHA; defaults to the caller ref'
+        type: string
+        required: false
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Optional tag, branch, or SHA; defaults to the selected workflow ref'
+        type: string
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  build-linux:
+    name: Linux ${{ matrix.arch }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-24.04, arch: x86_64}
+          - {os: ubuntu-24.04-arm, arch: aarch64}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: Build and smoke-test manylinux wheels
+        uses: pypa/cibuildwheel@294735312765b09d24a2fbec22660ce817587d55 # v4.1.0
+        env:
+          # The wheel has no Python ABI dependency; build once per architecture.
+          CIBW_BUILD: cp310-manylinux_${{ matrix.arch }}
+          CIBW_ARCHS_LINUX: ${{ matrix.arch }}
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+          CIBW_BEFORE_ALL_LINUX: >-
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh &&
+            sh /tmp/rustup-init.sh -y --profile minimal --default-toolchain 1.87.0
+          CIBW_ENVIRONMENT_LINUX: 'PATH="$HOME/.cargo/bin:$PATH" KCORAL_BUILD_RUST=1'
+          CIBW_TEST_COMMAND: kcoral router --help && kcoral-node --help
+        with:
+          output-dir: wheelhouse
+      - name: Check wheel metadata
+        run: uv tool run twine check --strict wheelhouse/*.whl
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: kcoral-dist-linux-${{ matrix.arch }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  build-pure:
+    name: Pure wheel and sdist
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: Build the sdist and a wheel without the Rust programs
+        env:
+          KCORAL_BUILD_RUST: '0'
+        run: uv build --out-dir dist
+      - name: Check the wheel is pure
+        run: |
+          wheel=$(ls dist/*-py3-none-any.whl)
+          if unzip -l "$wheel" | grep -E 'kcoral-(router|node)$'; then exit 1; fi
+      - name: Check metadata
+        run: uv tool run twine check --strict dist/*.whl dist/*.tar.gz
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: kcoral-dist-pure
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error

kcoral-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Documentation
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ['v[0-9]*']
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+
+concurrency:
+  group: documentation-${{ github.event_name == 'pull_request' && github.ref || 'publish' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  PUBLISH: ${{ github.repository == 'mlc-ai/kcoral' && github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')) }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # A new release rebuilds latest from main as well as every release tag.
+          ref: ${{ startsWith(github.ref, 'refs/tags/') && 'main' || github.ref }}
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: |
+            docs/requirements.txt
+            pyproject.toml
+      - name: Build the documentation website
+        run: python scripts/build_docs.py ${{ github.event_name == 'pull_request' && '--latest-only' || '' }}
+      - name: Publish to gh-pages
+        if: env.PUBLISH == 'true'
+        uses: peaceiris/actions-gh-pages@329bcc8f12caed2cefe5a5b80781499a6f3b361b # v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _site
+          publish_branch: gh-pages
+          cname: kcoral.mlc.ai
+      - name: Request GitHub Pages build
+        if: env.PUBLISH == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        # GITHUB_TOKEN pushes do not automatically trigger a Pages build.
+        run: gh api --method POST "repos/$GITHUB_REPOSITORY/pages/builds"

kcoral-0.1.1/.github/workflows/publish_pypi.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    uses: ./.github/workflows/build_wheels.yml
+    with:
+      ref: refs/tags/${{ github.event.release.tag_name }}
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kcoral
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: kcoral-dist-*
+          merge-multiple: true
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false
+          verbose: false

kcoral-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+venv/
+
+# Build artifacts
+build/
+dist/
+docs/_build/
+_site/
+.docs-venv/
+target/
+
+# Misc
+*.log
+tmp/
+**/logs

kcoral-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+# Formatting and hygiene checks.
+#
+# Run on the whole repo:
+#
+#   uvx pre-commit run --all-files
+#
+# Or install as a git hook so it runs on every commit:
+#
+#   uvx pre-commit install
+#
+# Update pinned hook versions with:
+#
+#   uvx pre-commit autoupdate
+
+repos:
+  # Standard hygiene hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        # Preserve the original high-resolution icon.
+        exclude: ^docs/_static/brand/kcoral-icon\.png$
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  # Python lint + format; configured in pyproject.toml [tool.ruff].
+  # ruff-check with the "I" rules also handles import sorting (isort).
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.22
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format