studio-workers 0.0.1__tar.gz → 1.4.0__tar.gz

studio_workers-1.4.0/LICENSE

@@ -0,0 +1,141 @@
+Studio Use License
+
+Copyright (c) 2025-2026 Kawika Ohumukini. All rights reserved.
+
+This license governs the use of the Studio software platform ("Software"),
+including its API, frontend, worker, and documentation components.
+
+This is not an open-source license. The source code is publicly available
+for transparency and community contribution, but commercial use is subject
+to the terms below.
+
+
+1. PERMITTED USE
+
+You may:
+
+  (a) Deploy and operate the Software for your own business purposes.
+
+  (b) Operate a hosted instance of the Software and charge customers for
+      access to it (SaaS model). There is no limit on the number of
+      customers or organizations on your instance.
+
+  (c) Provide consulting, installation, deployment, configuration, training,
+      and support services related to the Software.
+
+  (d) Deploy the Software for individual clients as part of bespoke service
+      engagements (one instance per client engagement).
+
+  (e) Provide the Software source code to your clients so they may deploy
+      and operate their own instance.
+
+  (f) Create, sell, and distribute your own workflow configurations,
+      templates, and automations. These are your intellectual property.
+
+  (g) Sell any output produced by the Software (images, video, text, data,
+      or any other generated content).
+
+  (h) Modify the Software for your own use.
+
+  (i) Contribute to this project.
+
+
+2. RESTRICTIONS
+
+You may not:
+
+  (a) Offer automated or self-service provisioning of Software instances
+      to third parties. You may not build a platform, tool, or service
+      whose primary function is deploying, hosting, or managing Software
+      instances on behalf of others.
+
+  (b) Distribute or sell pre-configured images, containers, deployment
+      packages, automation, or infrastructure templates that contain or
+      install the Software for third-party use.
+
+      Installing the Software on a client's own infrastructure using the
+      official Studio Console, as part of a service engagement, is
+      permitted and is not distribution under this section.
+
+  (c) Fork or rebrand the Software for resale or distribution as a
+      competing workflow automation platform or service.
+
+  (d) Redistribute, sublicense, or sell copies of the Software source
+      code as a standalone product or component.
+
+  (e) Remove or alter any copyright, trademark, or license notices
+      included in the Software.
+
+The distinction this license draws is between OPERATING and DISTRIBUTING.
+You may build a business that runs on Studio. You may not build a business
+that distributes Studio.
+
+For avoidance of doubt: operating a single Studio deployment as a
+multi-tenant service for customers is permitted. Offering Studio
+deployment, provisioning, or instance creation as a service to third
+parties is not.
+
+
+3. MARKETPLACE PACKAGES
+
+The Studio Marketplace (the studio-community and studio-plus repositories)
+provides optional provider packages, services, and templates under separate
+terms. Marketplace packages:
+
+  (a) Are licensed separately from this Software under their own terms.
+
+  (b) May not be redistributed, sideloaded, bundled, or transferred to
+      third-party deployments. Each deploying party must obtain marketplace
+      packages directly from the official marketplace.
+
+  (c) Are subject to the Studio Marketplace Package License, which governs
+      access, usage, and distribution.
+
+For clarity: workflow configurations that reference marketplace packages
+may be freely shared or sold. The marketplace packages themselves may not.
+
+Forking the public catalog repository to propose a contribution is
+permitted. Publishing or distributing packages from such a fork is not.
+
+
+4. USER-CREATED CONTENT
+
+Workflow configurations, templates, automations, field mappings, and other
+user-created content (typically JSON or similar configuration files) are the
+intellectual property of their creators. This license makes no claim on
+user-created content.
+
+
+5. TRADEMARKS
+
+"Studio," "Self-Host Studio," "Self-Host Hub," and associated logos and
+marks are trademarks of the copyright holder. Use of these trademarks is
+subject to applicable trademark law. You may use these names to truthfully
+describe your relationship with the Software (e.g., "built on Self-Host
+Studio," "powered by Studio"). You may not use the trademarks in a way
+that implies endorsement, affiliation, or origin without prior written
+consent. Nothing in this license grants the right to use these names or
+marks as part of a product name, company name, or primary branding.
+
+
+6. CONTRIBUTIONS
+
+Contributions to this project are assigned to the copyright holder and
+their successors and assigns. By submitting a contribution, you agree to
+this assignment and represent that you have the right to make the
+contribution.
+
+
+7. NO WARRANTY
+
+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, COPYRIGHT HOLDERS, OR CONTRIBUTORS 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.
+
+Operators are solely responsible for compliance with applicable laws and
+third-party service terms. See LEGAL.md for detailed operator obligations.

studio_workers-1.4.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: studio-workers
+Version: 1.4.0
+Summary: Studio workflow job workers
+Author: Kawika Ohumukini
+License-Expression: LicenseRef-Studio-Use-License
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: jsonpath-ng>=1.6.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: mutagen>=1.47.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: audio
+Requires-Dist: chatterbox-tts; extra == "audio"
+Requires-Dist: torch; extra == "audio"
+Requires-Dist: soundfile; extra == "audio"
+Requires-Dist: setuptools<81,>=78.1.1; extra == "audio"
+Provides-Extra: comfyui
+Requires-Dist: websocket-client>=1.6.0; extra == "comfyui"
+Provides-Extra: video
+Requires-Dist: openai-whisper>=20231117; extra == "video"
+Requires-Dist: faster-whisper>=1.0.0; extra == "video"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
+Requires-Dist: respx>=0.21.0; extra == "test"
+Requires-Dist: freezegun>=1.2.0; extra == "test"
+Requires-Dist: pyright>=1.1.405; extra == "test"
+Requires-Dist: flake8>=7.1.1; extra == "test"
+Requires-Dist: python-dotenv>=1.2.2; extra == "test"
+Dynamic: license-file
+
+# studio-workers
+
+Native (no-Docker) workers for [SelfHostHub Studio](https://www.skool.com/selfhosthub). Run any Studio worker engine directly on the host, pointed at your Studio API. This is the supported path for GPU work on Apple Silicon, where Docker cannot reach the Mac GPU, and for installing workers on demand inside a single GPU pod.
+
+## Install
+
+Pick the extra for the engine you want to run:
+
+```bash
+pip install "studio-workers[audio]"    # TTS (Chatterbox, torch)
+pip install "studio-workers[video]"    # transcription and video (whisper)
+pip install "studio-workers[comfyui]"  # ComfyUI bridge
+pip install "studio-workers"           # general + transfer (CPU only)
+```
+
+The `[audio]` extra currently requires Python 3.12: its Chatterbox dependency chain does not yet resolve on 3.13 (the install fails with an `llvmlite` build error). The other extras run on 3.12+.
+
+## Version pinning
+
+Install the `studio-workers` version that matches your Studio release; the release notes name it. The API checks the worker version at registration and refuses a mismatch.
+
+## Check the install
+
+```bash
+studio-workers doctor --engine audio
+```
+
+`doctor` fails loudly when a GPU host would silently run on CPU: it asserts torch sees MPS on Apple Silicon and CUDA when an NVIDIA driver is present.
+
+## Run
+
+```bash
+SHS_API_BASE_URL=https://your-studio-api \
+SHS_PUBLIC_BASE_URL=https://your-studio \
+SHS_WORKER_SHARED_SECRET=... \
+SHS_WORKSPACE_ROOT=/path/to/workspace \
+studio-workers run --type audio
+```
+
+(`python -m studio_workers.worker` with `SHS_WORKER_TYPE` set still works; `run` is the same loop.)
+
+The worker polls the API for jobs over HTTP; no inbound port is required. See your Studio instance's worker access documentation for the sanctioned connection paths.
+
+## Third-party software
+
+Installing an engine extra pulls third-party packages (torch, Chatterbox TTS, whisper, ComfyUI dependencies) from their own upstreams under their own licenses; model weights download on first run.

studio_workers-1.4.0/README.md

@@ -0,0 +1,56 @@
+# Studio Worker
+
+> **Community & support:** [SelfHostHub Community](https://www.skool.com/selfhosthub) · [Innovators (Plus)](https://www.skool.com/selfhostinnovators)
+
+HTTP polling-based background job processor for Studio.
+
+## Overview
+
+Handles async tasks: image generation, video processing, webhook delivery.
+
+## Local Development (Mac)
+
+### Prerequisites
+
+```bash
+# ffmpeg with libass (required for subtitle burn)
+# The default Homebrew bottle does NOT include libass.
+brew tap homebrew-ffmpeg/ffmpeg
+brew install homebrew-ffmpeg/ffmpeg/ffmpeg
+
+# Verify the ass filter is available
+ffmpeg -filters 2>&1 | grep -w ass
+```
+
+If you previously installed the default `ffmpeg` formula, replace it:
+
+```bash
+brew uninstall ffmpeg
+brew install homebrew-ffmpeg/ffmpeg/ffmpeg
+```
+
+### Video Worker
+
+```bash
+make video-local-setup   # Creates venv, installs deps, fonts
+make video-run-local     # Starts worker (polls API at localhost:8000)
+```
+
+**Apple Silicon GPU (MPS)**: Whisper transcription runs on the MPS GPU automatically. A monkey-patch handles Whisper's DTW alignment step which calls `.double()` (float64) - unsupported on MPS - by moving that tensor to CPU before conversion. Inference stays on GPU.
+
+### Audio Worker
+
+```bash
+make audio-local-setup   # Creates venv, installs Chatterbox TTS
+make audio-run-local     # Starts worker (MPS/CPU)
+```
+
+## Documentation
+
+See [docs/](../docs/) in the monorepo for full documentation.
+
+## License
+
+Studio Use License - See [LICENSE](LICENSE)
+
+For operator responsibilities and legal notices, see [LEGAL.md](LEGAL.md).

studio_workers-1.4.0/README.pypi.md

@@ -0,0 +1,46 @@
+# studio-workers
+
+Native (no-Docker) workers for [SelfHostHub Studio](https://www.skool.com/selfhosthub). Run any Studio worker engine directly on the host, pointed at your Studio API. This is the supported path for GPU work on Apple Silicon, where Docker cannot reach the Mac GPU, and for installing workers on demand inside a single GPU pod.
+
+## Install
+
+Pick the extra for the engine you want to run:
+
+```bash
+pip install "studio-workers[audio]"    # TTS (Chatterbox, torch)
+pip install "studio-workers[video]"    # transcription and video (whisper)
+pip install "studio-workers[comfyui]"  # ComfyUI bridge
+pip install "studio-workers"           # general + transfer (CPU only)
+```
+
+The `[audio]` extra currently requires Python 3.12: its Chatterbox dependency chain does not yet resolve on 3.13 (the install fails with an `llvmlite` build error). The other extras run on 3.12+.
+
+## Version pinning
+
+Install the `studio-workers` version that matches your Studio release; the release notes name it. The API checks the worker version at registration and refuses a mismatch.
+
+## Check the install
+
+```bash
+studio-workers doctor --engine audio
+```
+
+`doctor` fails loudly when a GPU host would silently run on CPU: it asserts torch sees MPS on Apple Silicon and CUDA when an NVIDIA driver is present.
+
+## Run
+
+```bash
+SHS_API_BASE_URL=https://your-studio-api \
+SHS_PUBLIC_BASE_URL=https://your-studio \
+SHS_WORKER_SHARED_SECRET=... \
+SHS_WORKSPACE_ROOT=/path/to/workspace \
+studio-workers run --type audio
+```
+
+(`python -m studio_workers.worker` with `SHS_WORKER_TYPE` set still works; `run` is the same loop.)
+
+The worker polls the API for jobs over HTTP; no inbound port is required. See your Studio instance's worker access documentation for the sanctioned connection paths.
+
+## Third-party software
+
+Installing an engine extra pulls third-party packages (torch, Chatterbox TTS, whisper, ComfyUI dependencies) from their own upstreams under their own licenses; model weights download on first run.

studio_workers-1.4.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "studio-workers"
+dynamic = ["version"]
+description = "Studio workflow job workers"
+readme = "README.pypi.md"
+requires-python = ">=3.12"
+license = "LicenseRef-Studio-Use-License"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Kawika Ohumukini"}
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "psutil>=5.9.0",
+    "jsonpath-ng>=1.6.0",
+    "Pillow>=10.0.0",
+    "rich>=13.0.0",
+    "mutagen>=1.47.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.scripts]
+studio-workers = "studio_workers.cli:main"
+
+[project.optional-dependencies]
+audio = [
+    "chatterbox-tts",
+    "torch",
+    "soundfile",
+    # resemble-perth needs pkg_resources (gone in setuptools 82, warns in 81); uv venvs ship
+    # no setuptools at all, so the extra must provide a CVE-fixed one itself.
+    "setuptools>=78.1.1,<81",
+]
+comfyui = [
+    "websocket-client>=1.6.0",
+]
+video = [
+    "openai-whisper>=20231117",
+    "faster-whisper>=1.0.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "pytest-httpx>=0.30.0",
+    "pytest-xdist>=3.0.0",
+    "respx>=0.21.0",
+    "freezegun>=1.2.0",
+    "pyright>=1.1.405",
+    "flake8>=7.1.1",
+    "python-dotenv>=1.2.2",  # test-time only: conftest.py pre-loads envs/.env.test before shared.settings imports
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "studio_workers.contracts.version.WORKERS_VERSION"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = [
+    "-v",
+    "--tb=short",
+    "--strict-markers",
+]
+markers = [
+    "unit: Unit tests (no external dependencies)",
+    "integration: Integration tests (may need mocked services)",
+    "slow: Tests that take significant time",
+]
+
+[tool.coverage.run]
+source = ["studio_workers"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/.venv/*",
+    # Shared contracts package: gated by api/tests/unit/contracts, not the workers suite.
+    "studio_workers/contracts/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+show_missing = true
+
+[tool.setuptools.packages.find]
+include = ["studio_workers*"]
+exclude = ["tests*", "docker*", "typestubs*"]
+
+[tool.setuptools.package-data]
+"studio_workers.engines.comfyui" = ["presets/*.json", "workflows/*.json"]
+"studio_workers.engines.video" = ["fonts/*", "fonts/licenses/*"]

studio_workers-1.4.0/studio_workers/__init__.py

@@ -0,0 +1,3 @@
+# workers/studio_workers/__init__.py
+
+"""Shared utilities, constants, and base classes for all worker types."""

studio_workers-1.4.0/studio_workers/adapters/__init__.py

@@ -0,0 +1,3 @@
+# workers/studio_workers/adapters/__init__.py
+
+# Worker adapters - standalone implementations for worker execution

studio_workers-1.4.0/studio_workers/cli.py

@@ -0,0 +1,108 @@
+# workers/studio_workers/cli.py
+
+"""studio-workers console entrypoint: `doctor` (environment check) and `run` (start a worker)."""
+
+import argparse
+import platform
+import shutil
+import sys
+
+from studio_workers.contracts.version import WORKERS_VERSION
+
+# Engines whose inference runs torch locally; the others need no GPU here
+# (comfyui proxies to an external ComfyUI server, general/transfer are CPU).
+TORCH_ENGINES = {"audio", "video"}
+
+
+def _expected_accelerator() -> str | None:
+    """The accelerator this host should expose: mps on Apple Silicon, cuda when
+    an NVIDIA driver is present, else None (CPU is legitimate)."""
+    if sys.platform == "darwin" and platform.machine() == "arm64":
+        return "mps"
+    if sys.platform.startswith("linux") and shutil.which("nvidia-smi"):
+        return "cuda"
+    return None
+
+
+def _torch_device() -> tuple[str | None, str | None]:
+    """(device, torch version); device None when torch is not installed."""
+    try:
+        import torch
+    except ImportError:
+        return None, None
+    if torch.cuda.is_available():
+        return "cuda", torch.__version__
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps", torch.__version__
+    return "cpu", torch.__version__
+
+
+def doctor(engine: str | None) -> int:
+    """Report the environment and fail loudly when a GPU host would silently run on CPU."""
+    print(f"studio-workers {WORKERS_VERSION}")
+    print(f"python {platform.python_version()} on {sys.platform}/{platform.machine()}")
+
+    expected = _expected_accelerator()
+    device, torch_version = _torch_device()
+
+    if device is None:
+        if engine in TORCH_ENGINES:
+            print(
+                f"ERROR: torch is not installed but the {engine} engine needs it. "
+                f'Install the engine extra: pip install "studio-workers[{engine}]=={WORKERS_VERSION}"'
+            )
+            return 1
+        print("torch: not installed (not required for this engine)")
+        return 0
+
+    print(f"torch {torch_version}, device={device}")
+    if expected and device == "cpu":
+        hint = (
+            "Docker cannot reach the Mac GPU; run natively (this install) with an MPS-enabled torch wheel."
+            if expected == "mps"
+            else "Reinstall torch from the matching CUDA index (https://download.pytorch.org/whl/) for your driver."
+        )
+        print(
+            f"ERROR: this host exposes {expected} but torch only sees the CPU; "
+            f"generation would run uselessly slow instead of failing. {hint}"
+        )
+        return 1
+    return 0
+
+
+def run(worker_type: str | None) -> int:
+    """Start the worker loop; --type overrides SHS_WORKER_TYPE."""
+    import os
+
+    if worker_type:
+        os.environ["SHS_WORKER_TYPE"] = worker_type
+
+    from studio_workers import worker
+
+    worker.main()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="studio-workers")
+    parser.add_argument("--version", action="version", version=WORKERS_VERSION)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_doctor = sub.add_parser("doctor", help="check this host can run a worker")
+    p_doctor.add_argument(
+        "--engine",
+        choices=["general", "transfer", "video", "audio", "comfyui"],
+        help="engine you intend to run; makes torch mandatory for audio/video",
+    )
+
+    p_run = sub.add_parser("run", help="start a worker (same loop as python -m studio_workers.worker)")
+    p_run.add_argument("--type", dest="worker_type", help="worker type; overrides SHS_WORKER_TYPE")
+
+    args = parser.parse_args(argv)
+    if args.command == "doctor":
+        return doctor(args.engine)
+    return run(args.worker_type)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

studio_workers-1.4.0/studio_workers/constants.py

@@ -0,0 +1 @@
+# workers/studio_workers/constants.py

studio_workers-1.4.0/studio_workers/contracts/__init__.py

@@ -0,0 +1,82 @@
+# workers/studio_workers/contracts/__init__.py
+
+"""
+Shared contract types between API and workers.
+
+Pydantic models define canonical payload shapes for cross-component
+communication. Log schema defines canonical JSON log field names.
+Both sides import from here - one source of truth.
+
+Python 3.11 compatible (workers use 3.11, API uses 3.12).
+"""
+
+from studio_workers.contracts.log_schema import (
+    FIELD_CORRELATION_ID,
+    FIELD_EXCEPTION,
+    FIELD_EXTRA,
+    FIELD_HOST,
+    FIELD_LEVEL,
+    FIELD_LOGGER,
+    FIELD_MESSAGE,
+    FIELD_SERVICE,
+    FIELD_TIMESTAMP,
+    VERBOSITY_FULL,
+    VERBOSITY_MINIMAL,
+    VERBOSITY_STANDARD,
+    format_timestamp,
+    get_log_verbosity,
+)
+from studio_workers.contracts.redaction import (
+    PII_KEYS,
+    REDACTED_PLACEHOLDER,
+    SENSITIVE_KEYS,
+    is_pii_key,
+    is_sensitive_key,
+    redact_sensitive_data,
+    redact_url,
+)
+
+__all__ = [
+    "DownloadedFileContract",
+    "JobClaimContract",
+    "StepResultContract",
+    "FIELD_TIMESTAMP",
+    "FIELD_LEVEL",
+    "FIELD_SERVICE",
+    "FIELD_MESSAGE",
+    "FIELD_HOST",
+    "FIELD_LOGGER",
+    "FIELD_CORRELATION_ID",
+    "FIELD_EXCEPTION",
+    "FIELD_EXTRA",
+    "VERBOSITY_MINIMAL",
+    "VERBOSITY_STANDARD",
+    "VERBOSITY_FULL",
+    "get_log_verbosity",
+    "format_timestamp",
+    "SENSITIVE_KEYS",
+    "PII_KEYS",
+    "REDACTED_PLACEHOLDER",
+    "is_sensitive_key",
+    "is_pii_key",
+    "redact_sensitive_data",
+    "redact_url",
+]
+
+
+def __getattr__(name: str):
+    """Lazy-import pydantic-dependent contracts to avoid pulling in pydantic
+    for lightweight consumers (e.g., workers that only need log_schema)."""
+    if name == "DownloadedFileContract":
+        from studio_workers.contracts.downloaded_file import DownloadedFileContract
+
+        return DownloadedFileContract
+    if name == "JobClaimContract":
+        from studio_workers.contracts.job_claim import JobClaimContract
+
+        return JobClaimContract
+    if name == "StepResultContract":
+        from studio_workers.contracts.step_result import StepResultContract
+
+        return StepResultContract
+    raise AttributeError(f"module 'contracts' has no attribute {name!r}")