holix-sdk 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: uv sync --group dev
+
+      - name: Ruff
+        run: uv run ruff check holix_sdk tests
+
+      - name: Pytest
+        run: uv run pytest -q

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

@@ -0,0 +1,71 @@
+# Create a GitHub Release when a version tag is pushed.
+#
+# Tag must match pyproject.toml and holix_sdk/version.py (same rule as publish-pypi.yml).
+#
+# Typical flow:
+#   1. Bump version in pyproject.toml + holix_sdk/version.py
+#   2. git tag vX.Y.Z && git push origin vX.Y.Z
+#   3. This workflow creates the GitHub Release
+#   4. publish-pypi.yml publishes holix-sdk to PyPI
+name: GitHub Release
+
+on:
+  push:
+    tags:
+      - v*
+
+concurrency:
+  group: github-release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve version from tag
+        id: ver
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          VERSION="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Verify tag matches package version
+        run: |
+          EXPECTED="${{ steps.ver.outputs.version }}"
+          ACTUAL=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          PY_VERSION=$(python -c "import pathlib; p=pathlib.Path('holix_sdk/version.py'); print([l.split('=')[1].strip().strip('\"') for l in p.read_text().splitlines() if l.strip().startswith('__version__')][0])")
+          if [ "$EXPECTED" != "$ACTUAL" ]; then
+            echo "::error::Git tag v$EXPECTED does not match pyproject.toml version $ACTUAL"
+            exit 1
+          fi
+          if [ "$EXPECTED" != "$PY_VERSION" ]; then
+            echo "::error::Git tag v$EXPECTED does not match holix_sdk/version.py $PY_VERSION"
+            exit 1
+          fi
+          echo "Version OK: $ACTUAL"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.ver.outputs.tag }}
+          name: holix-sdk ${{ steps.ver.outputs.version }}
+          body: |
+            ## holix-sdk ${{ steps.ver.outputs.version }}
+
+            Stable public API for Holix extension authors.
+
+            ```bash
+            pip install holix-sdk==${{ steps.ver.outputs.version }}
+            ```
+
+            Docs: [EXTENSIONS.md](https://github.com/javded-itres/holix-sdk/blob/${{ steps.ver.outputs.tag }}/docs/en/EXTENSIONS.md)
+          draft: false
+          prerelease: false
+          make_latest: true

holix_sdk-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,145 @@
+# Publish holix-sdk to PyPI via GitHub Actions.
+#
+# Auth: PyPI Trusted Publishing (OIDC) — recommended, no token in secrets.
+# Fallback: set PYPI_API_TOKEN / TEST_PYPI_API_TOKEN and choose "api-token" when running manually.
+#
+# One-time setup:
+#   1. GitHub → Settings → Environments → create "pypi" (and "testpypi" for dry runs)
+#   2. PyPI → project holix-sdk → Publishing → Add trusted publisher:
+#        Owner: javded-itres | Repository: holix-sdk
+#        Workflow filename: publish-pypi.yml | Environment name: pypi
+#   3. (Optional) Repeat on https://test.pypi.org for environment "testpypi"
+#
+# Release by tag (recommended):
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Manual run: Actions → Publish to PyPI → Run workflow
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: Upload to TestPyPI instead of PyPI
+        required: false
+        default: false
+        type: boolean
+      auth:
+        description: Authentication (use api-token only if Trusted Publishing is not configured)
+        required: false
+        default: trusted-publishing
+        type: choice
+        options:
+          - trusted-publishing
+          - api-token
+  push:
+    tags:
+      - v*
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: uv sync --group dev --no-install-project
+
+      - name: Verify tag matches package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          PY_VERSION=$(python -c "import pathlib; p=pathlib.Path('holix_sdk/version.py'); print([l.split('=')[1].strip().strip('\"') for l in p.read_text().splitlines() if l.strip().startswith('__version__')][0])")
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "::error::Git tag v$TAG does not match pyproject.toml version $VERSION"
+            exit 1
+          fi
+          if [ "$TAG" != "$PY_VERSION" ]; then
+            echo "::error::Git tag v$TAG does not match holix_sdk/version.py $PY_VERSION"
+            exit 1
+          fi
+          echo "Version OK: $VERSION"
+
+      - name: Build package
+        run: uv build
+
+      - name: Validate artifacts
+        run: uv run twine check dist/*
+
+      - name: Smoke install wheel
+        run: |
+          uv venv /tmp/holix-sdk-publish-smoke --python 3.12
+          uv pip install --python /tmp/holix-sdk-publish-smoke/bin/python dist/holix_sdk-*.whl
+          /tmp/holix-sdk-publish-smoke/bin/python -c "
+          import holix_sdk
+          from holix_sdk.agent import AgentExtensionBase, SlashCommandSpec
+          assert holix_sdk.__api_version__ == 1
+          assert holix_sdk.CAPABILITY_CLI == 'cli'
+          assert AgentExtensionBase is not None
+          assert SlashCommandSpec is not None
+          print('holix-sdk', holix_sdk.__version__, 'api', holix_sdk.__api_version__)
+          "
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.testpypi && 'testpypi' || 'pypi' }}
+    permissions:
+      id-token: write
+      contents: read
+    env:
+      TO_TESTPYPI: ${{ github.event_name == 'workflow_dispatch' && inputs.testpypi && 'true' || 'false' }}
+      USE_API_TOKEN: ${{ github.event_name == 'workflow_dispatch' && inputs.auth == 'api-token' && 'true' || 'false' }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: List artifacts
+        run: ls -la dist/
+
+      - name: Publish to TestPyPI (Trusted Publishing)
+        if: env.TO_TESTPYPI == 'true' && env.USE_API_TOKEN != 'true'
+        run: uv publish --publish-url https://test.pypi.org/legacy/ dist/*
+
+      - name: Publish to TestPyPI (API token)
+        if: env.TO_TESTPYPI == 'true' && env.USE_API_TOKEN == 'true'
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        run: uv publish --publish-url https://test.pypi.org/legacy/ dist/*
+
+      - name: Publish to PyPI (Trusted Publishing)
+        if: env.TO_TESTPYPI != 'true' && env.USE_API_TOKEN != 'true'
+        run: uv publish dist/*
+
+      - name: Publish to PyPI (API token)
+        if: env.TO_TESTPYPI != 'true' && env.USE_API_TOKEN == 'true'
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish dist/*

holix_sdk-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.DS_Store
+.idea/
+.vscode/
+uv.lock

holix_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holix Contributors
+
+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.

holix_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: holix-sdk
+Version: 0.1.0
+Summary: Stable public API for Holix extensions and host integrations
+Project-URL: Homepage, https://holix-agent.ru
+Project-URL: Repository, https://github.com/javded-itres/holix-sdk
+Project-URL: Documentation, https://github.com/javded-itres/holix-sdk/blob/main/docs/en/EXTENSIONS.md
+Project-URL: Issues, https://github.com/javded-itres/holix-sdk/issues
+Author: Pavel Lukyanov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,extensions,holix,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: holix>=0.1.21
+Description-Content-Type: text/markdown
+
+# holix-sdk
+
+[![CI](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml)
+
+**Separate installable package** — stable public API for [Holix](https://github.com/javded-itres/Holix) extension authors.
+
+Holix core (`core.*`, `cli.*`) is internal. Extension packages import **only** `holix_sdk`.
+
+## Install
+
+```bash
+pip install holix-sdk Holix
+```
+
+Requires [Holix](https://pypi.org/project/Holix/) `>=0.1.21` on PyPI.
+
+## API version
+
+```python
+from holix_sdk import __api_version__
+# Currently: 1
+```
+
+Breaking changes to the extension API happen only in major releases of `holix-sdk`.
+
+## Quick example
+
+```python
+from holix_sdk import ExtensionBase, CAPABILITY_CLI
+from holix_sdk.agent import AgentExtensionBase, SlashCommandSpec
+from holix_sdk.host import AgentCommands
+```
+
+## Documentation
+
+| Language | Guide |
+|----------|-------|
+| English | [docs/en/EXTENSIONS.md](docs/en/EXTENSIONS.md) |
+| Russian | [docs/ru/EXTENSIONS.md](docs/ru/EXTENSIONS.md) |
+
+## Development
+
+```bash
+git clone git@github.com:javded-itres/holix-sdk.git
+cd holix-sdk
+uv sync --group dev
+uv run pytest -q
+```
+
+## Publish
+
+Automated via GitHub Actions on tag `v*` — see [docs/PYPI.md](docs/PYPI.md).
+
+```bash
+# bump pyproject.toml + holix_sdk/version.py, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Local check:
+
+```bash
+uv build && uv run twine check dist/*
+```
+
+PyPI package name: `holix-sdk`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

holix_sdk-0.1.0/README.md

@@ -0,0 +1,69 @@
+# holix-sdk
+
+[![CI](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/javded-itres/holix-sdk/actions/workflows/ci.yml)
+
+**Separate installable package** — stable public API for [Holix](https://github.com/javded-itres/Holix) extension authors.
+
+Holix core (`core.*`, `cli.*`) is internal. Extension packages import **only** `holix_sdk`.
+
+## Install
+
+```bash
+pip install holix-sdk Holix
+```
+
+Requires [Holix](https://pypi.org/project/Holix/) `>=0.1.21` on PyPI.
+
+## API version
+
+```python
+from holix_sdk import __api_version__
+# Currently: 1
+```
+
+Breaking changes to the extension API happen only in major releases of `holix-sdk`.
+
+## Quick example
+
+```python
+from holix_sdk import ExtensionBase, CAPABILITY_CLI
+from holix_sdk.agent import AgentExtensionBase, SlashCommandSpec
+from holix_sdk.host import AgentCommands
+```
+
+## Documentation
+
+| Language | Guide |
+|----------|-------|
+| English | [docs/en/EXTENSIONS.md](docs/en/EXTENSIONS.md) |
+| Russian | [docs/ru/EXTENSIONS.md](docs/ru/EXTENSIONS.md) |
+
+## Development
+
+```bash
+git clone git@github.com:javded-itres/holix-sdk.git
+cd holix-sdk
+uv sync --group dev
+uv run pytest -q
+```
+
+## Publish
+
+Automated via GitHub Actions on tag `v*` — see [docs/PYPI.md](docs/PYPI.md).
+
+```bash
+# bump pyproject.toml + holix_sdk/version.py, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Local check:
+
+```bash
+uv build && uv run twine check dist/*
+```
+
+PyPI package name: `holix-sdk`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

holix_sdk-0.1.0/docs/PYPI.md

@@ -0,0 +1,57 @@
+# Publishing holix-sdk to PyPI
+
+Package name on PyPI: **`holix-sdk`**
+
+```bash
+pip install holix-sdk
+```
+
+Requires [Holix](https://pypi.org/project/Holix/) `>=0.1.21`.
+
+## Automated release (GitHub Actions)
+
+Workflow: [`.github/workflows/publish-pypi.yml`](../.github/workflows/publish-pypi.yml)
+
+### One-time PyPI setup
+
+1. Create PyPI project `holix-sdk` (or claim on first upload).
+2. GitHub repo **holix-sdk** → Settings → Environments → create `pypi` (and `testpypi` for dry runs).
+3. PyPI → **holix-sdk** → Publishing → **Add trusted publisher**:
+   - Owner: `javded-itres`
+   - Repository: `holix-sdk`
+   - Workflow: `publish-pypi.yml`
+   - Environment: `pypi`
+4. (Optional) Same on [TestPyPI](https://test.pypi.org) for environment `testpypi`.
+
+### Release steps
+
+1. Bump version in **both** files:
+   - `pyproject.toml` → `[project].version`
+   - `holix_sdk/version.py` → `__version__`
+2. Commit and push to `main`.
+3. Tag and push:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+This triggers:
+
+- **GitHub Release** (`github-release.yml`)
+- **Publish to PyPI** (`publish-pypi.yml`)
+
+### Manual publish
+
+Actions → **Publish to PyPI** → Run workflow
+
+- Enable **TestPyPI** for a dry run first.
+- Use **api-token** only if Trusted Publishing is not configured (`PYPI_API_TOKEN` / `TEST_PYPI_API_TOKEN` secrets).
+
+## Local build check
+
+```bash
+uv sync --group dev
+uv build
+uv run twine check dist/*
+```