larex-action-sdk 0.1.0__tar.gz

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

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest
+      - run: uv build

larex_action_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*rc*"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: ${{ github.event_name == 'release' && !github.event.release.prerelease && !contains(github.event.release.tag_name, 'rc') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/larex-action-sdk
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    if: ${{ (github.event_name == 'push' && contains(github.ref_name, 'rc')) || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/larex-action-sdk
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv run pytest
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

larex_action_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.pyright/
+dist/
+htmlcov/
+coverage.xml
+__pycache__/
+*.py[cod]
+.idea

larex_action_sdk-0.1.0/LICENSE

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

larex_action_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: larex-action-sdk
+Version: 0.1.0
+Summary: Framework-neutral Python SDK for building LAREX Action processors.
+Project-URL: Homepage, https://github.com/OCR4all/larex-action-sdk
+Project-URL: Repository, https://github.com/OCR4all/larex-action-sdk
+Project-URL: Issues, https://github.com/OCR4all/larex-action-sdk/issues
+Author: OCR4all
+License-Expression: MIT
+License-File: LICENSE
+Keywords: actions,larex,ocr,processors
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.115; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# LAREX Action SDK
+
+> This SDK is work in progress. The public API can still change before LAREX
+> Actions and the SDK are considered stable.
+
+Framework-neutral Python SDK for building [LAREX](https://github.com/OCR4all/larex)
+Action processors.
+
+The core package verifies LAREX dispatch requests, parses typed run/input payloads,
+sends heartbeats, downloads selected files, and uploads result manifests. FastAPI
+support is available as an optional convenience extra.
+
+## Installation
+
+```bash
+uv add "larex-action-sdk[fastapi]"
+```
+
+For framework-neutral usage only:
+
+```bash
+uv add larex-action-sdk
+```
+
+## FastAPI Processor
+
+```python
+import os
+
+from larex_actions import ActionContext
+from larex_actions.fastapi import create_larex_action_app
+
+
+async def process(ctx: ActionContext) -> None:
+    action_input = await ctx.pull_input()
+    results = ctx.result_builder()
+
+    for page in action_input.pages:
+        await ctx.heartbeat(25, f"Processing {page.name}", raise_on_cancel=True)
+        if page.xml:
+            xml_bytes = await ctx.download_bytes(page.xml[0])
+            results.add_xml_bytes(
+                page_id=page.id,
+                content=xml_bytes,
+                file_name=f"{page.name}-processed.xml",
+                variant="processed",
+            )
+
+    await ctx.complete(results, "Done")
+
+
+app = create_larex_action_app(
+    processor_id="my-processor",
+    dispatch_secret=os.environ["LAREX_DISPATCH_HMAC_SECRET"],
+    handler=process,
+)
+```
+
+## Framework-Neutral Dispatch Verification
+
+```python
+from larex_actions import DispatchVerifier
+
+payload = DispatchVerifier(
+    processor_id="my-processor",
+    dispatch_secret=secret,
+).verify(
+    method=request_method,
+    path_and_query=request_path_and_query,
+    headers=request_headers,
+    body=request_body,
+)
+```
+
+You can then pass `payload.model_dump(mode="json", by_alias=True)` to your own
+queue/worker system and use `ActionClient.from_dispatch(payload)` in async workers.
+
+## Security
+
+- Dispatch requests are verified with the `X-LAREX-Action-*` HMAC headers.
+- Timestamps and nonces are checked to reduce replay risk.
+- Per-run bearer secrets and dispatch HMAC secrets are never included in model reprs.
+- Processor YAML must still declare the inputs and outputs LAREX should expose or accept.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+uv build
+```
+
+Releases are published with PyPI Trusted Publishing from GitHub Actions. Release
+candidate tags containing `rc` publish to TestPyPI; published GitHub releases
+publish to PyPI.

larex_action_sdk-0.1.0/README.md

@@ -0,0 +1,98 @@
+# LAREX Action SDK
+
+> This SDK is work in progress. The public API can still change before LAREX
+> Actions and the SDK are considered stable.
+
+Framework-neutral Python SDK for building [LAREX](https://github.com/OCR4all/larex)
+Action processors.
+
+The core package verifies LAREX dispatch requests, parses typed run/input payloads,
+sends heartbeats, downloads selected files, and uploads result manifests. FastAPI
+support is available as an optional convenience extra.
+
+## Installation
+
+```bash
+uv add "larex-action-sdk[fastapi]"
+```
+
+For framework-neutral usage only:
+
+```bash
+uv add larex-action-sdk
+```
+
+## FastAPI Processor
+
+```python
+import os
+
+from larex_actions import ActionContext
+from larex_actions.fastapi import create_larex_action_app
+
+
+async def process(ctx: ActionContext) -> None:
+    action_input = await ctx.pull_input()
+    results = ctx.result_builder()
+
+    for page in action_input.pages:
+        await ctx.heartbeat(25, f"Processing {page.name}", raise_on_cancel=True)
+        if page.xml:
+            xml_bytes = await ctx.download_bytes(page.xml[0])
+            results.add_xml_bytes(
+                page_id=page.id,
+                content=xml_bytes,
+                file_name=f"{page.name}-processed.xml",
+                variant="processed",
+            )
+
+    await ctx.complete(results, "Done")
+
+
+app = create_larex_action_app(
+    processor_id="my-processor",
+    dispatch_secret=os.environ["LAREX_DISPATCH_HMAC_SECRET"],
+    handler=process,
+)
+```
+
+## Framework-Neutral Dispatch Verification
+
+```python
+from larex_actions import DispatchVerifier
+
+payload = DispatchVerifier(
+    processor_id="my-processor",
+    dispatch_secret=secret,
+).verify(
+    method=request_method,
+    path_and_query=request_path_and_query,
+    headers=request_headers,
+    body=request_body,
+)
+```
+
+You can then pass `payload.model_dump(mode="json", by_alias=True)` to your own
+queue/worker system and use `ActionClient.from_dispatch(payload)` in async workers.
+
+## Security
+
+- Dispatch requests are verified with the `X-LAREX-Action-*` HMAC headers.
+- Timestamps and nonces are checked to reduce replay risk.
+- Per-run bearer secrets and dispatch HMAC secrets are never included in model reprs.
+- Processor YAML must still declare the inputs and outputs LAREX should expose or accept.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run pytest
+uv build
+```
+
+Releases are published with PyPI Trusted Publishing from GitHub Actions. Release
+candidate tags containing `rc` publish to TestPyPI; published GitHub releases
+publish to PyPI.

larex_action_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "larex-action-sdk"
+version = "0.1.0"
+description = "Framework-neutral Python SDK for building LAREX Action processors."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "OCR4all" }
+]
+keywords = ["larex", "ocr", "actions", "processors"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+dependencies = [
+  "httpx>=0.28,<1",
+  "pydantic>=2.10,<3"
+]
+
+[project.optional-dependencies]
+fastapi = [
+  "fastapi>=0.115,<1"
+]
+
+[project.urls]
+Homepage = "https://github.com/OCR4all/larex-action-sdk"
+Repository = "https://github.com/OCR4all/larex-action-sdk"
+Issues = "https://github.com/OCR4all/larex-action-sdk/issues"
+
+[dependency-groups]
+dev = [
+  "fastapi>=0.115,<1",
+  "pyright>=1.1.407",
+  "pytest>=8.3,<9",
+  "pytest-asyncio>=0.25,<1",
+  "ruff>=0.9,<1"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/larex_actions"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "PTH", "RUF"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false

larex_action_sdk-0.1.0/src/larex_actions/__init__.py

@@ -0,0 +1,38 @@
+from .client import ActionClient, ActionContext
+from .exceptions import ActionCancelled, DispatchVerificationError, LarexActionError
+from .models import (
+    ActionDispatchPayload,
+    ActionFile,
+    ActionInput,
+    ActionPage,
+    FileType,
+    HeartbeatResponse,
+    ResultFile,
+    ResultManifest,
+    ResultStatus,
+    RunStatus,
+)
+from .nonce import NonceStore
+from .results import ResultBuilder
+from .verifier import DispatchVerifier
+
+__all__ = [
+    "ActionCancelled",
+    "ActionClient",
+    "ActionContext",
+    "ActionDispatchPayload",
+    "ActionFile",
+    "ActionInput",
+    "ActionPage",
+    "DispatchVerificationError",
+    "DispatchVerifier",
+    "FileType",
+    "HeartbeatResponse",
+    "LarexActionError",
+    "NonceStore",
+    "ResultBuilder",
+    "ResultFile",
+    "ResultManifest",
+    "ResultStatus",
+    "RunStatus",
+]

larex_action_sdk-0.1.0/src/larex_actions/client.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .exceptions import ActionCancelled
+from .models import (
+    ActionDispatchPayload,
+    ActionFile,
+    ActionInput,
+    HeartbeatResponse,
+    ResultStatus,
+    RunStatus,
+)
+from .results import ResultBuilder
+
+
+class ActionClient:
+    def __init__(
+        self,
+        *,
+        pull_url: str,
+        heartbeat_url: str,
+        result_url: str,
+        secret: str,
+        client: httpx.AsyncClient | None = None,
+        timeout: float | httpx.Timeout = 120.0,
+    ) -> None:
+        self.pull_url = pull_url
+        self.heartbeat_url = heartbeat_url
+        self.result_url = result_url
+        self._secret = secret
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+    @classmethod
+    def from_dispatch(
+        cls,
+        payload: ActionDispatchPayload,
+        *,
+        client: httpx.AsyncClient | None = None,
+        timeout: float | httpx.Timeout = 120.0,
+    ) -> ActionClient:
+        return cls(
+            pull_url=payload.pull_url,
+            heartbeat_url=payload.heartbeat_url,
+            result_url=payload.result_url,
+            secret=payload.secret.get_secret_value(),
+            client=client,
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> ActionClient:
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def pull_input(self) -> ActionInput:
+        response = await self._client.get(self.pull_url, headers=self._auth_headers())
+        response.raise_for_status()
+        return ActionInput.model_validate(response.json())
+
+    async def heartbeat(
+        self,
+        progress_percent: int | None = None,
+        status_message: str | None = None,
+        *,
+        log: str | None = None,
+        status: RunStatus = "running",
+        error_message: str | None = None,
+        raise_on_cancel: bool = False,
+    ) -> HeartbeatResponse:
+        payload: dict[str, Any] = {
+            "status": status,
+            "progressPercent": progress_percent,
+            "statusMessage": status_message,
+            "log": log,
+            "errorMessage": error_message,
+        }
+        response = await self._client.post(
+            self.heartbeat_url,
+            headers=self._auth_headers(),
+            json={key: value for key, value in payload.items() if value is not None},
+        )
+        response.raise_for_status()
+        heartbeat = HeartbeatResponse.model_validate(response.json())
+        if raise_on_cancel and heartbeat.cancel_requested:
+            raise ActionCancelled("LAREX requested cancellation")
+        return heartbeat
+
+    async def download_bytes(self, file: ActionFile) -> bytes:
+        response = await self._client.get(file.download_url, headers=self._auth_headers())
+        response.raise_for_status()
+        return response.content
+
+    async def download_to_path(self, file: ActionFile, path: str | Path) -> Path:
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        async with self._client.stream(
+            "GET",
+            file.download_url,
+            headers=self._auth_headers(),
+        ) as response:
+            response.raise_for_status()
+            with target.open("wb") as output:
+                async for chunk in response.aiter_bytes():
+                    output.write(chunk)
+        return target
+
+    async def complete(
+        self,
+        results: ResultBuilder,
+        message: str | None = None,
+    ) -> Mapping[str, Any]:
+        return await self._post_results(results, status="completed", message=message)
+
+    async def upload_results(
+        self,
+        results: ResultBuilder,
+        *,
+        status: ResultStatus = "completed",
+        message: str | None = None,
+    ) -> Mapping[str, Any]:
+        return await self._post_results(results, status=status, message=message)
+
+    async def fail(
+        self,
+        message: str,
+        *,
+        log: str | None = None,
+        progress_percent: int | None = None,
+    ) -> HeartbeatResponse:
+        return await self.heartbeat(
+            progress_percent=progress_percent,
+            status_message=message,
+            log=log,
+            status="failed",
+            error_message=message,
+        )
+
+    async def _post_results(
+        self,
+        results: ResultBuilder,
+        *,
+        status: ResultStatus,
+        message: str | None,
+    ) -> Mapping[str, Any]:
+        with ExitStack() as exit_stack:
+            response = await self._client.post(
+                self.result_url,
+                headers=self._auth_headers(),
+                files=results.httpx_files(status=status, message=message, exit_stack=exit_stack),
+            )
+        response.raise_for_status()
+        data = response.json()
+        return data if isinstance(data, Mapping) else {"response": data}
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._secret}"}
+
+
+class ActionContext:
+    def __init__(self, *, payload: ActionDispatchPayload, client: ActionClient) -> None:
+        self.payload = payload
+        self.client = client
+
+    @property
+    def run_id(self) -> str:
+        return self.payload.run_id
+
+    @property
+    def processor_id(self) -> str:
+        return self.payload.processor_id
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return self.payload.parameters
+
+    async def pull_input(self) -> ActionInput:
+        return await self.client.pull_input()
+
+    async def heartbeat(
+        self,
+        progress_percent: int | None = None,
+        status_message: str | None = None,
+        *,
+        log: str | None = None,
+        raise_on_cancel: bool = False,
+    ) -> HeartbeatResponse:
+        return await self.client.heartbeat(
+            progress_percent=progress_percent,
+            status_message=status_message,
+            log=log,
+            raise_on_cancel=raise_on_cancel,
+        )
+
+    async def raise_if_cancelled(self) -> None:
+        await self.heartbeat(raise_on_cancel=True)
+
+    async def download_bytes(self, file: ActionFile) -> bytes:
+        return await self.client.download_bytes(file)
+
+    async def download_to_path(self, file: ActionFile, path: str | Path) -> Path:
+        return await self.client.download_to_path(file, path)
+
+    def result_builder(self) -> ResultBuilder:
+        return ResultBuilder()
+
+    async def complete(
+        self,
+        results: ResultBuilder,
+        message: str | None = None,
+    ) -> Mapping[str, Any]:
+        return await self.client.complete(results, message)
+
+    async def upload_results(
+        self,
+        results: ResultBuilder,
+        *,
+        status: ResultStatus = "completed",
+        message: str | None = None,
+    ) -> Mapping[str, Any]:
+        return await self.client.upload_results(results, status=status, message=message)
+
+    async def fail(self, message: str, *, log: str | None = None) -> HeartbeatResponse:
+        return await self.client.fail(message, log=log)

larex_action_sdk-0.1.0/src/larex_actions/exceptions.py

@@ -0,0 +1,14 @@
+class LarexActionError(Exception):
+    """Base exception raised by the LAREX Action SDK."""
+
+
+class DispatchVerificationError(LarexActionError):
+    """Raised when an incoming dispatch request cannot be trusted."""
+
+    def __init__(self, message: str, *, status_code: int = 401) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ActionCancelled(LarexActionError):
+    """Raised when LAREX asks the processor to stop cooperatively."""