clerk-sdk 0.4.5__tar.gz → 0.4.6__tar.gz

clerk_sdk-0.4.6/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: clerk-sdk
+Version: 0.4.6
+Summary: Library for interacting with Clerk
+Home-page: https://github.com/F-ONE-Group/clerk_pypi
+Author: F-ONE Group
+Author-email: admin@f-one.group
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: backoff<3.0.0,>=2.0.0
+Requires-Dist: requests<3.0.0,>=2.32.3
+Provides-Extra: all
+Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "all"
+Requires-Dist: backoff<3.0.0,>=2.0.0; extra == "all"
+Requires-Dist: requests<3.0.0,>=2.32.3; extra == "all"
+Requires-Dist: networkx<4.0.0,>=3.5.0; extra == "all"
+Requires-Dist: websockets>=15.0.1; extra == "all"
+Provides-Extra: gui-automation
+Requires-Dist: networkx<4.0.0,>=3.5.0; extra == "gui-automation"
+Requires-Dist: websockets>=15.0.1; extra == "gui-automation"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Clerk Python SDK
+
+A production-ready Python client for the Clerk API. The SDK wraps Clerk's REST endpoints, rich document models, automation helpers, and structured task decorators so that your applications can create, update, and process Clerk documents with minimal boilerplate.
+
+## Table of Contents
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+  - [Instantiate a Client](#instantiate-a-client)
+  - [Fetch Documents](#fetch-documents)
+  - [Upload a Document](#upload-a-document)
+  - [Update Structured Data](#update-structured-data)
+  - [Work with Files](#work-with-files)
+- [Automation Utilities](#automation-utilities)
+  - [Task Decorator](#task-decorator)
+  - [GUI Automation Toolkit](#gui-automation-toolkit)
+- [Error Handling](#error-handling)
+- [Development Workflow](#development-workflow)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+The Clerk SDK centers around the `Clerk` client (`clerk.client.Clerk`), which extends a resilient `BaseClerk` transport layer with automatic retries and typed responses. Models under `clerk.models` provide Pydantic-powered validation for documents, files, and API payloads, ensuring type safety across network boundaries. Additional modules cover automated task execution via the `clerk.decorator` package and UI workflows under `clerk.gui_automation`.
+
+## Key Features
+- **Document lifecycle management** – Create, fetch, list, and update Clerk documents with first-class models.
+- **File handling** – Upload binary files or parsed base64 payloads and attach them to documents.
+- **Robust networking** – Automatic retries for transient HTTP issues, configurable base URLs, and bearer authentication out of the box.
+- **Structured task execution** – Decorators for running Clerk tasks locally or inside worker environments with consistent pickle-based I/O.
+- **GUI automations** – Utilities for orchestrating low-level UI actions, state machines, and operator interactions when human-in-the-loop steps are required.
+
+## Requirements
+- Python 3.10+
+- Dependencies listed in [`requirements.txt`](requirements.txt), including `pydantic` and `backoff`.
+
+## Installation
+Install the SDK from PyPI:
+
+```bash
+pip install clerk-sdk
+```
+
+For local development inside this repository, install the dependencies in editable mode:
+
+```bash
+pip install -e .[dev]
+```
+
+## Configuration
+The client reads configuration from keyword arguments or environment variables.
+
+| Setting | Environment Variable | Description |
+| --- | --- | --- |
+| API key | `CLERK_API_KEY` | Required secret used for bearer authentication. |
+| Base URL | `CLERK_BASE_URL` | Optional override of the default API host (`https://api.clerk-app.com`). |
+
+```bash
+export CLERK_API_KEY="sk_live_123"
+export CLERK_BASE_URL="https://staging.clerk-app.com"  # optional
+```
+
+You can also pass the API key directly when instantiating `Clerk`:
+
+```python
+from clerk import Clerk
+
+client = Clerk(api_key="sk_live_123")
+```
+
+## Quick Start
+The following snippets demonstrate the core document operations supported by the SDK.
+
+### Instantiate a Client
+```python
+from clerk import Clerk
+
+client = Clerk(api_key="sk_live_123")
+```
+
+### Fetch Documents
+Retrieve a single document by its identifier or list documents with query filters.
+
+```python
+from clerk.models.document import GetDocumentsRequest
+
+# Single document
+invoice = client.get_document(document_id="doc_123")
+print(invoice.title, invoice.status)
+
+# Query multiple documents
+request = GetDocumentsRequest(project_id="proj_456", limit=25)
+documents = client.get_documents(request)
+for doc in documents:
+    print(doc.id, doc.status)
+```
+
+### Upload a Document
+Use `UploadDocumentRequest` to send metadata and file attachments. Files can be supplied as paths or `ParsedFile` instances.
+
+```python
+from clerk.models.document import UploadDocumentRequest
+
+upload_request = UploadDocumentRequest(
+    project_id="proj_456",
+    message_subject="Invoice 2024-01",
+    files=["/path/to/invoice.pdf"],
+    input_structured_data={"customer_id": "cust_789"},
+)
+
+created = client.upload_document(upload_request)
+print(f"Created document: {created.id}")
+```
+
+### Update Structured Data
+Patch a document's structured payload without re-uploading files.
+
+```python
+updated = client.update_document_structured_data(
+    document_id="doc_123",
+    updated_structured_data={"status": "processed", "processed_by": "automation"},
+)
+print(updated.structured_data)
+```
+
+### Work with Files
+Retrieve parsed file metadata or attach additional files to existing documents.
+
+```python
+from clerk.models.file import UploadFile
+
+# List associated files
+files = client.get_files_document(document_id="doc_123")
+for file in files:
+    print(file.name, file.mimetype)
+
+# Append output files
+client.add_files_to_document(
+    document_id="doc_123",
+    type="output",
+    files=[
+        UploadFile(name="summary.txt", mimetype="text/plain", content=b"Processed")
+    ],
+)
+```
+
+## Custom Code Utilities
+### Task Decorator
+The `@clerk_code` decorator standardizes how Clerk tasks load inputs and persist outputs when executed by the Clerk workflow. It automatically reads a pickled `ClerkCodePayload` from `/app/data/input/input.pkl`, executes your function, and writes the result (or an `ApplicationException`) to `/app/data/output/output.pkl`.
+
+```python
+from clerk.decorator import clerk_code
+from clerk.decorator.models import ClerkCodePayload, Document
+
+@clerk_code()
+def handle_document(payload: ClerkCodePayload) -> ClerkCodePayload:
+    document: Document = payload.document
+    payload.structured_data = payload.structured_data or {}
+    payload.structured_data["status"] = f"Processed {document.id}"
+    return payload
+
+if __name__ == "__main__":
+    handle_document()  # Auto-loads from pickle files when payload is omitted
+```
+
+For unit testing, you can bypass the pickle integration by passing an explicit payload instance:
+
+```python
+from datetime import datetime
+from clerk.decorator.models import ClerkCodePayload, Document
+from clerk.models.document_statuses import DocumentStatuses
+
+sample_payload = ClerkCodePayload(
+    document=Document(
+        id="doc_123",
+        project_id="proj_456",
+        title="Sample",
+        upload_date=datetime.utcnow(),
+        status=DocumentStatuses.draft,
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow(),
+    ),
+    structured_data={},
+)
+result = handle_document(sample_payload)
+assert "Processed" in result.structured_data["status"]
+```
+
+> **Note:** Refer to `tests/test_task_decorator.py` for additional usage examples covering error propagation and pickle round-trips.
+
+### GUI Automation Toolkit
+The `clerk.gui_automation` package contains models, actions, and state machines for orchestrating UI interactions. Highlights include:
+
+- `BaseAction` and concrete actions for cursor movement, clicks, and keyboard input.
+- `ActionModel` builders that translate payloads into executable UI sequences.
+- State machine primitives (`ui_state_machine`) to coordinate multi-step automations.
+- Helpers for safely reading files, validating anchors, and converting payload flags.
+
+These utilities are designed to be composed with your own automation runners or integrated into Clerk tasks. Review the tests in `tests/test_gui_automation.py` for patterns on stubbing operator clients and verifying payload transformations.
+
+## Error Handling
+All network helpers raise `requests` exceptions for HTTP errors. When using the task decorator, runtime failures are wrapped in `ApplicationException` objects that capture the exception type, message, and traceback for easier debugging. Deserialize the returned payload or inspect the pickle output to handle errors gracefully.
+
+## Development Workflow
+1. **Clone the repository** and install dependencies with `pip install -e .[dev]`.
+2. **Run the test suite** using `pytest`. The CI workflow executes these tests before packaging releases.
+3. **Add type-safe models** or extend the client in `clerk/client.py` and `clerk/models` as needed.
+4. **Contribute automations** under `clerk/gui_automation` by following the established action/state machine patterns.
+5. **Commit and open a pull request** once tests pass and documentation is updated.
+
+## Contributing
+Contributions are welcome! Please open an issue to discuss substantial changes, follow the existing code style (Pydantic models, typed functions, and pytest fixtures), and ensure the test suite passes before submitting a pull request.
+
+## License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

clerk_sdk-0.4.6/README.md

@@ -0,0 +1,217 @@
+# Clerk Python SDK
+
+A production-ready Python client for the Clerk API. The SDK wraps Clerk's REST endpoints, rich document models, automation helpers, and structured task decorators so that your applications can create, update, and process Clerk documents with minimal boilerplate.
+
+## Table of Contents
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+  - [Instantiate a Client](#instantiate-a-client)
+  - [Fetch Documents](#fetch-documents)
+  - [Upload a Document](#upload-a-document)
+  - [Update Structured Data](#update-structured-data)
+  - [Work with Files](#work-with-files)
+- [Automation Utilities](#automation-utilities)
+  - [Task Decorator](#task-decorator)
+  - [GUI Automation Toolkit](#gui-automation-toolkit)
+- [Error Handling](#error-handling)
+- [Development Workflow](#development-workflow)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+The Clerk SDK centers around the `Clerk` client (`clerk.client.Clerk`), which extends a resilient `BaseClerk` transport layer with automatic retries and typed responses. Models under `clerk.models` provide Pydantic-powered validation for documents, files, and API payloads, ensuring type safety across network boundaries. Additional modules cover automated task execution via the `clerk.decorator` package and UI workflows under `clerk.gui_automation`.
+
+## Key Features
+- **Document lifecycle management** – Create, fetch, list, and update Clerk documents with first-class models.
+- **File handling** – Upload binary files or parsed base64 payloads and attach them to documents.
+- **Robust networking** – Automatic retries for transient HTTP issues, configurable base URLs, and bearer authentication out of the box.
+- **Structured task execution** – Decorators for running Clerk tasks locally or inside worker environments with consistent pickle-based I/O.
+- **GUI automations** – Utilities for orchestrating low-level UI actions, state machines, and operator interactions when human-in-the-loop steps are required.
+
+## Requirements
+- Python 3.10+
+- Dependencies listed in [`requirements.txt`](requirements.txt), including `pydantic` and `backoff`.
+
+## Installation
+Install the SDK from PyPI:
+
+```bash
+pip install clerk-sdk
+```
+
+For local development inside this repository, install the dependencies in editable mode:
+
+```bash
+pip install -e .[dev]
+```
+
+## Configuration
+The client reads configuration from keyword arguments or environment variables.
+
+| Setting | Environment Variable | Description |
+| --- | --- | --- |
+| API key | `CLERK_API_KEY` | Required secret used for bearer authentication. |
+| Base URL | `CLERK_BASE_URL` | Optional override of the default API host (`https://api.clerk-app.com`). |
+
+```bash
+export CLERK_API_KEY="sk_live_123"
+export CLERK_BASE_URL="https://staging.clerk-app.com"  # optional
+```
+
+You can also pass the API key directly when instantiating `Clerk`:
+
+```python
+from clerk import Clerk
+
+client = Clerk(api_key="sk_live_123")
+```
+
+## Quick Start
+The following snippets demonstrate the core document operations supported by the SDK.
+
+### Instantiate a Client
+```python
+from clerk import Clerk
+
+client = Clerk(api_key="sk_live_123")
+```
+
+### Fetch Documents
+Retrieve a single document by its identifier or list documents with query filters.
+
+```python
+from clerk.models.document import GetDocumentsRequest
+
+# Single document
+invoice = client.get_document(document_id="doc_123")
+print(invoice.title, invoice.status)
+
+# Query multiple documents
+request = GetDocumentsRequest(project_id="proj_456", limit=25)
+documents = client.get_documents(request)
+for doc in documents:
+    print(doc.id, doc.status)
+```
+
+### Upload a Document
+Use `UploadDocumentRequest` to send metadata and file attachments. Files can be supplied as paths or `ParsedFile` instances.
+
+```python
+from clerk.models.document import UploadDocumentRequest
+
+upload_request = UploadDocumentRequest(
+    project_id="proj_456",
+    message_subject="Invoice 2024-01",
+    files=["/path/to/invoice.pdf"],
+    input_structured_data={"customer_id": "cust_789"},
+)
+
+created = client.upload_document(upload_request)
+print(f"Created document: {created.id}")
+```
+
+### Update Structured Data
+Patch a document's structured payload without re-uploading files.
+
+```python
+updated = client.update_document_structured_data(
+    document_id="doc_123",
+    updated_structured_data={"status": "processed", "processed_by": "automation"},
+)
+print(updated.structured_data)
+```
+
+### Work with Files
+Retrieve parsed file metadata or attach additional files to existing documents.
+
+```python
+from clerk.models.file import UploadFile
+
+# List associated files
+files = client.get_files_document(document_id="doc_123")
+for file in files:
+    print(file.name, file.mimetype)
+
+# Append output files
+client.add_files_to_document(
+    document_id="doc_123",
+    type="output",
+    files=[
+        UploadFile(name="summary.txt", mimetype="text/plain", content=b"Processed")
+    ],
+)
+```
+
+## Custom Code Utilities
+### Task Decorator
+The `@clerk_code` decorator standardizes how Clerk tasks load inputs and persist outputs when executed by the Clerk workflow. It automatically reads a pickled `ClerkCodePayload` from `/app/data/input/input.pkl`, executes your function, and writes the result (or an `ApplicationException`) to `/app/data/output/output.pkl`.
+
+```python
+from clerk.decorator import clerk_code
+from clerk.decorator.models import ClerkCodePayload, Document
+
+@clerk_code()
+def handle_document(payload: ClerkCodePayload) -> ClerkCodePayload:
+    document: Document = payload.document
+    payload.structured_data = payload.structured_data or {}
+    payload.structured_data["status"] = f"Processed {document.id}"
+    return payload
+
+if __name__ == "__main__":
+    handle_document()  # Auto-loads from pickle files when payload is omitted
+```
+
+For unit testing, you can bypass the pickle integration by passing an explicit payload instance:
+
+```python
+from datetime import datetime
+from clerk.decorator.models import ClerkCodePayload, Document
+from clerk.models.document_statuses import DocumentStatuses
+
+sample_payload = ClerkCodePayload(
+    document=Document(
+        id="doc_123",
+        project_id="proj_456",
+        title="Sample",
+        upload_date=datetime.utcnow(),
+        status=DocumentStatuses.draft,
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow(),
+    ),
+    structured_data={},
+)
+result = handle_document(sample_payload)
+assert "Processed" in result.structured_data["status"]
+```
+
+> **Note:** Refer to `tests/test_task_decorator.py` for additional usage examples covering error propagation and pickle round-trips.
+
+### GUI Automation Toolkit
+The `clerk.gui_automation` package contains models, actions, and state machines for orchestrating UI interactions. Highlights include:
+
+- `BaseAction` and concrete actions for cursor movement, clicks, and keyboard input.
+- `ActionModel` builders that translate payloads into executable UI sequences.
+- State machine primitives (`ui_state_machine`) to coordinate multi-step automations.
+- Helpers for safely reading files, validating anchors, and converting payload flags.
+
+These utilities are designed to be composed with your own automation runners or integrated into Clerk tasks. Review the tests in `tests/test_gui_automation.py` for patterns on stubbing operator clients and verifying payload transformations.
+
+## Error Handling
+All network helpers raise `requests` exceptions for HTTP errors. When using the task decorator, runtime failures are wrapped in `ApplicationException` objects that capture the exception type, message, and traceback for easier debugging. Deserialize the returned payload or inspect the pickle output to handle errors gracefully.
+
+## Development Workflow
+1. **Clone the repository** and install dependencies with `pip install -e .[dev]`.
+2. **Run the test suite** using `pytest`. The CI workflow executes these tests before packaging releases.
+3. **Add type-safe models** or extend the client in `clerk/client.py` and `clerk/models` as needed.
+4. **Contribute automations** under `clerk/gui_automation` by following the established action/state machine patterns.
+5. **Commit and open a pull request** once tests pass and documentation is updated.
+
+## Contributing
+Contributions are welcome! Please open an issue to discuss substantial changes, follow the existing code style (Pydantic models, typed functions, and pytest fixtures), and ensure the test suite passes before submitting a pull request.
+
+## License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

{clerk_sdk-0.4.5 → clerk_sdk-0.4.6}/clerk/__init__.py

@@ -1 +1,4 @@
 from .client import Clerk
+
+
+__version__ = "0.4.6"

clerk_sdk-0.4.6/clerk/client.py

@@ -0,0 +1,138 @@
+from typing import Any, Dict, List, Literal
+
+from clerk.base import BaseClerk
+from clerk.models.document import Document, GetDocumentsRequest, UploadDocumentRequest
+from .models.file import ParsedFile, UploadFile
+
+
+class Clerk(BaseClerk):
+
+    def upload_document(self, request: UploadDocumentRequest) -> Document:
+        endpoint = "/document"
+        res = self.post_request(
+            endpoint=endpoint, data=request.data, files=request.files_
+        )
+        return Document(**res.data[0])
+
+    def cancel_document_run(self, document_id: str) -> Document:
+        endpoint = f"/document/{document_id}/cancel"
+        res = self.post_request(endpoint=endpoint)
+        return Document(**res.data[0])
+
+    def update_document_structured_data(
+        self, document_id: str, updated_structured_data: Dict[str, Any]
+    ) -> Document:
+        endpoint = f"/document/{document_id}"
+        payload = dict(structured_data=updated_structured_data)
+        res = self.put_request(endpoint, json=payload)
+
+        return Document(**res.data[0])
+
+    def get_document(self, document_id: str) -> Document:
+        endpoint = f"/document/{document_id}"
+        res = self.get_request(endpoint=endpoint)
+        return Document(**res.data[0])
+
+    def get_documents(self, request: GetDocumentsRequest) -> List[Document]:
+        if not any(
+            [
+                request.organization_id,
+                request.project_id,
+                request.start_date,
+                request.end_date,
+                request.query,
+                request.include_statuses,
+            ]
+        ):
+            raise ValueError(
+                "At least one query parameter (organization_id, project_id, start_date, end_date, query, or include_statuses) must be provided."
+            )
+
+        endpoint = f"/documents"
+        params = request.model_dump(mode="json")
+        res = self.get_request(endpoint, params=params)
+
+        return [Document(**d) for d in res.data]
+
+    def get_files_document(self, document_id: str) -> List[ParsedFile]:
+        endpoint = f"/document/{document_id}/files"
+        res = self.get_request(endpoint=endpoint)
+        return [ParsedFile(**d) for d in res.data]
+
+    def add_files_to_document(
+        self,
+        document_id: str,
+        type: Literal["input", "output"],
+        files: List[UploadFile],
+    ):
+        endpoint = f"/document/{document_id}/files/upload"
+        params = {"type": type}
+        files_data = [f.to_multipart_format() for f in files]
+        self.post_request(endpoint, params=params, files=files_data)
+
+
+class ClerkDocument(BaseClerk):
+    endpoint: str = "/document"
+
+    def upload_document(self, request: UploadDocumentRequest) -> Document:
+        endpoint = "/document"
+        res = self.post_request(
+            endpoint=endpoint, data=request.data, files=request.files_
+        )
+        return Document(**res.data[0])
+
+    def cancel_document_run(self, document_id: str) -> Document:
+        endpoint = f"/document/{document_id}/cancel"
+        res = self.post_request(endpoint=endpoint)
+        return Document(**res.data[0])
+
+    def update_document_structured_data(
+        self, document_id: str, updated_structured_data: Dict[str, Any]
+    ) -> Document:
+        endpoint = f"/document/{document_id}"
+        payload = dict(structured_data=updated_structured_data)
+        res = self.put_request(endpoint, json=payload)
+
+        return Document(**res.data[0])
+
+    def get_document(self, document_id: str) -> Document:
+        endpoint = f"/document/{document_id}"
+        res = self.get_request(endpoint=endpoint)
+        return Document(**res.data[0])
+
+    def get_documents(self, request: GetDocumentsRequest) -> List[Document]:
+        if not any(
+            [
+                request.organization_id,
+                request.project_id,
+                request.start_date,
+                request.end_date,
+                request.query,
+                request.include_statuses,
+            ]
+        ):
+            raise ValueError(
+                "At least one query parameter (organization_id, project_id, start_date, end_date, query, or include_statuses) must be provided."
+            )
+
+        endpoint = f"/documents"
+        params = request.model_dump(mode="json")
+        res = self.get_request(endpoint, params=params)
+
+        return [Document(**d) for d in res.data]
+
+    def get_files_document(self, document_id: str) -> List[ParsedFile]:
+        endpoint = f"/document/{document_id}/files"
+        res = self.get_request(endpoint=endpoint)
+        return [ParsedFile(**d) for d in res.data]
+
+    def add_files_to_document(
+        self,
+        document_id: str,
+        type: Literal["input", "output"],
+        files: List[UploadFile],
+    ):
+        endpoint = f"/document/{document_id}/files/upload"
+        params = {"type": type}
+        files_data = [f.to_multipart_format() for f in files]
+        self.post_request(endpoint, params=params, files=files_data)

{clerk_sdk-0.4.5 → clerk_sdk-0.4.6}/clerk/utils/logger.py

@@ -6,7 +6,10 @@ import sys
 if sys.platform == "win32":
     base_path = os.path.join(os.getcwd(), "data", "artifacts")
 else:
-    base_path = "/app/data/artifacts"
+    if os.getenv("__TEST"):
+        base_path = os.path.join(os.getcwd(), "data", "artifacts")
+    else:
+        base_path = "/app/data/artifacts"
 
 os.makedirs(base_path, exist_ok=True)