kitaru 0.1.0__tar.gz

kitaru-0.1.0/.claude/settings.json

@@ -0,0 +1,13 @@
+{
+  "extraKnownMarketplaces": {
+    "astral-sh": {
+      "source": {
+        "source": "github",
+        "repo": "astral-sh/claude-code-plugins"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "astral@astral-sh": true
+  }
+}

kitaru-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+---
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: tuesday
+      time: 07:00
+      timezone: Europe/Amsterdam
+    reviewers: [strickvl]
+    labels: [dependencies]
+    groups:
+      all-actions:
+        patterns: ['*']
+    target-branch: develop

kitaru-0.1.0/.github/teams.yml

@@ -0,0 +1,10 @@
+---
+internal:
+  - '@htahir1'
+  - '@bcdurak'
+  - '@schustmi'
+  - '@strickvl'
+  - '@AlexejPenner'
+  - '@stefannica'
+  - '@safoinme'
+  - '@Cahllagerfeld'

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

@@ -0,0 +1,52 @@
+---
+name: CI
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run yamlfix --check .github/
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@v1
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ty check
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: --root-dir . --verbose --no-progress './**/*.md'
+          fail: true
+          jobSummary: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - run: uv run pytest

kitaru-0.1.0/.github/workflows/image-optimiser.yml

@@ -0,0 +1,25 @@
+---
+name: Compress Images
+on:
+  pull_request:
+    # Run Image Actions when JPG, JPEG, PNG or WebP files are added or changed.
+    # See https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpaths for reference.
+    paths: ['**.jpg', '**.jpeg', '**.png', '**.webp']
+permissions:
+  contents: write
+jobs:
+  build:
+    # Only run on non-draft PRs within the same repository.
+    if: github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.draft
+      == false
+    name: calibreapp/image-actions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Compress Images
+        uses: calibreapp/image-actions@737ceeaeed61e17b8d358358a303f1b8d177b779  # 1.1.0
+        with:
+          # The `GITHUB_TOKEN` is automatically generated by GitHub and scoped only to the repository that is currently running the action. By default, the action can’t update Pull Requests initiated from forked repositories.
+          # See https://docs.github.com/en/actions/reference/authentication-in-a-workflow and https://help.github.com/en/articles/virtual-environments-for-github-actions#token-permissions
+          githubToken: ${{ secrets.GITHUB_TOKEN }}

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

@@ -0,0 +1,166 @@
+---
+name: Release
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to release (e.g. 0.2.0)
+        required: true
+        type: string
+      dry-run:
+        description: Dry run (build and test but do not publish or push)
+        required: false
+        type: boolean
+        default: false
+  push:
+    tags: [v*]
+permissions:
+  contents: write
+  id-token: write
+concurrency:
+  group: release
+  cancel-in-progress: false
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true' && '' || 'pypi' }}
+    steps:
+      # --- Determine version and trigger mode ---
+      - name: Set version from dispatch
+        if: github.event_name == 'workflow_dispatch'
+        run: echo "VERSION=${{ github.event.inputs.version }}" >> "$GITHUB_ENV"
+      - name: Set version from tag
+        if: github.event_name == 'push'
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
+
+      # --- Validate version ---
+      - name: Validate semver format
+        run: |
+          if ! echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$'; then
+            echo "::error::Invalid version format: $VERSION (expected semver like 1.2.3 or 1.2.3-rc.1)"
+            exit 1
+          fi
+      - name: Check tag does not already exist (dispatch only)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if git ls-remote --tags origin "refs/tags/v$VERSION" | grep -q .; then
+            echo "::error::Tag v$VERSION already exists"
+            exit 1
+          fi
+
+      # --- Checkout ---
+      - name: Checkout develop (dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/checkout@v4
+        with:
+          ref: develop
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Checkout tagged commit (tag push)
+        if: github.event_name == 'push'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # --- Configure git ---
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # --- Bump version (dispatch only) ---
+      - name: Bump version in pyproject.toml
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          echo "Updated pyproject.toml to version $VERSION"
+          grep '^version' pyproject.toml
+      - name: Update CHANGELOG.md
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          DATE=$(date +%Y-%m-%d)
+          sed -i "s/^## \[Unreleased\]/## [Unreleased]\n\n## [$VERSION] - $DATE/" CHANGELOG.md
+          echo "Updated CHANGELOG.md for $VERSION ($DATE)"
+      - name: Commit release changes
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          git add pyproject.toml CHANGELOG.md
+          git commit -m "Release $VERSION"
+
+      # --- Verify version matches (tag push only) ---
+      - name: Verify tag matches pyproject.toml version
+        if: github.event_name == 'push'
+        run: |
+          TOML_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          if [ "$TOML_VERSION" != "$VERSION" ]; then
+            echo "::error::Tag version ($VERSION) does not match pyproject.toml ($TOML_VERSION)"
+            exit 1
+          fi
+
+      # --- Run CI checks ---
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Type check
+        run: uv run ty check
+      - name: Test
+        run: uv run pytest
+
+      # --- Build ---
+      - name: Build package
+        run: uv build
+      - name: List build artifacts
+        run: ls -lh dist/
+
+      # --- Publish (skip on dry-run) ---
+      - name: Publish to PyPI
+        if: ${{ !(github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true') }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      # --- Push release commit to develop (dispatch only, skip on dry-run) ---
+      - name: Push release commit to develop
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run != 'true' }}
+        run: git push origin HEAD:develop
+
+      # --- Create release branch and update main (skip on dry-run) ---
+      - name: Create release branch
+        if: ${{ !(github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true') }}
+        run: |
+          git checkout -b "release/$VERSION"
+          git push origin "release/$VERSION"
+      - name: Update main to release
+        if: ${{ !(github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true') }}
+        run: git push --force origin "release/$VERSION:main"
+
+      # --- Tag (dispatch only, skip on dry-run) ---
+      - name: Create and push tag
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run != 'true' }}
+        run: |
+          git tag "v$VERSION"
+          git push origin "v$VERSION"
+
+      # --- GitHub Release (skip on dry-run) ---
+      - name: Create GitHub Release
+        if: ${{ !(github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true') }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "v$VERSION" dist/* \
+            --title "v$VERSION" \
+            --generate-notes
+
+      # --- Dry-run summary ---
+      - name: Dry-run summary
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.dry-run == 'true' }}
+        run: |-
+          echo "## Dry-run complete" >> "$GITHUB_STEP_SUMMARY"
+          echo "Version: $VERSION" >> "$GITHUB_STEP_SUMMARY"
+          echo "Build artifacts:" >> "$GITHUB_STEP_SUMMARY"
+          ls dist/ >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "No changes were pushed, published, or tagged." >> "$GITHUB_STEP_SUMMARY"

kitaru-0.1.0/.github/workflows/spellcheck.yml

@@ -0,0 +1,26 @@
+---
+name: Spellcheck
+on:
+  workflow_dispatch:
+  workflow_call:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+    types: [opened, synchronize, reopened, ready_for_review]
+concurrency:
+  # New commit on branch cancels running workflows of the same branch
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  spellcheck:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Spelling checker
+        uses: crate-ci/typos@2361394247a38536a5f2376a05181ca001dd9e26  # v1.17.0
+        with:
+          files: .
+          config: ./.typos.toml

kitaru-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Design docs
+design/
+
+# MCP
+.mcp.json
+
+# Claude
+**/.claude/settings.local.json
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+
+# Codex
+.codex/*
+!.codex/skills/
+AGENTS.override.md

kitaru-0.1.0/.typos.toml

@@ -0,0 +1,17 @@
+[files]
+extend-exclude = [
+    "*.json",
+    "*.js",
+    "*.ipynb",
+    "uv.lock",
+]
+
+[default.extend-identifiers]
+HashiCorp = "HashiCorp"
+
+[default.extend-words]
+# Don't correct the surname "Teh"
+aks = "aks"
+
+[default]
+locale = "en-us"

kitaru-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Kitaru is a Python 3.12+ project for durable AI agent execution on ZenML. Use a `src` layout:
+- `src/kitaru/`: core package and runtime primitives
+- `src/kitaru/cli.py`: CLI entry point using [cyclopts](https://cyclopts.readthedocs.io/)
+- `src/kitaru/adapters/`: framework integrations (for example PydanticAI)
+- `tests/`: `pytest` test suite, mirroring package paths
+- `design/`: design notes and meeting docs (ignored by git; do not commit)
+
+At the moment, the repository is still bootstrapping; place new production code under `src/kitaru/` and tests under `tests/`.
+
+## Build, Test, and Development Commands
+Use `uv` for dependency management and `just` as the command runner.
+- `uv sync`: install and sync dependencies
+- `just check`: run all checks (format, lint, typecheck, typos, yaml)
+- `just test`: run full test suite
+- `just test tests/test_file.py::test_name`: run one test
+- `just fix`: auto-fix formatting, lint issues, and yaml
+- `just lint`: run lint checks only
+- `just typecheck`: run static type checks only
+- `just typos`: run typo/spelling checks only
+- `just build`: build wheel and sdist locally
+
+## Coding Style & Naming Conventions
+- Follow US English spelling in code and docs (`initialize`, `serialize`, `color`).
+- Use type hints on all public functions and return values.
+- Prefer modern annotations (`list[str]`, `str | None`) over legacy `typing` aliases.
+- Follow Google Python style for docstrings.
+- Keep comments focused on *why* (intent/trade-offs), not line-by-line narration.
+- Treat leading underscore names as private to module/class boundaries.
+- Prefer Protocols/ABCs or `isinstance` over `getattr`/`hasattr` for capability checks.
+- Put helpers on the class when tied to its behavior; use standalone utils only for generic cross-module functions.
+- Prefer Pydantic models for data structures; checkpoint return values must be serializable.
+
+## CLI
+The `kitaru` console script is defined in `pyproject.toml` under `[project.scripts]` and implemented with cyclopts in `src/kitaru/cli.py`. Add subcommands via `@app.command`. When testing CLI commands, always pass an explicit arg list (`app(["--help"])`, not bare `app()`). CLI invocations raise `SystemExit(0)` on success.
+
+## Testing Guidelines
+Use `pytest` for unit and integration tests. Name files `test_*.py` and test functions `test_*`. Mirror source paths (example: `src/kitaru/runtime.py` -> `tests/test_runtime.py`). Every bug fix should include a regression test that fails before the fix and passes after it.
+
+## Commit & Pull Request Guidelines
+Recent history uses short, imperative subjects (for example: `Add ...`, `Update ...`, `Create ...`). Keep commit titles concise (about 50 chars), and explain the why in the body when needed.
+
+For pull requests, use a clear human-readable title and include:
+- what changed
+- why it was needed
+- key implementation decisions
+- reviewer focus areas
+
+Link related issues (for example `Fixes #123`) when applicable.
+
+## CI
+CI (`.github/workflows/ci.yml`) runs lint, type check, typos, and tests on push/PR to `develop` against Python 3.12 and 3.13.
+Typo checking uses `crate-ci/typos` with config in `.typos.toml`.
+
+## Branching and Release Strategy
+
+- Default branch is `develop`. All PRs target `develop`.
+- `main` tracks the latest released version only; do not push directly.
+- Releases are cut via the Release workflow (`workflow_dispatch` on `develop` or `v*` tag push).
+- Release branches (`release/X.Y.Z`) and tags (`vX.Y.Z`) are created automatically.
+- Version is maintained in `pyproject.toml` and bumped by the release workflow.
+
+## Security & Configuration Notes
+Do not commit local secrets, `.env` files, or anything in `design/`. Use `uv` (not raw `pip`) for dependency management to keep environments reproducible.

kitaru-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-06
+
+### Added
+- Initial project scaffolding with uv, ruff, ty, and CI
+- CLI with cyclopts (`kitaru --version`, `kitaru --help`)
+- Justfile for common development commands
+- Link checking with lychee
+- Typo checking with typos