runqy-python 0.2.0__tar.gz

runqy_python-0.2.0/LICENSE

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

runqy_python-0.2.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: runqy-python
+Version: 0.2.0
+Summary: Python SDK for runqy - write distributed task handlers with simple decorators
+Author: Publikey
+Project-URL: Documentation, https://docs.runqy.com
+Project-URL: Repository, https://github.com/Publikey/runqy-python
+Project-URL: Issues, https://github.com/Publikey/runqy-python/issues
+Keywords: task-queue,distributed,worker,redis,async,client
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+<p align="center">
+  <img src="assets/logo.svg" alt="runqy logo" width="80" height="80">
+</p>
+
+<h1 align="center">runqy-python</h1>
+
+<p align="center">
+  Python SDK for <a href="https://runqy.com">runqy</a> - write distributed task handlers with simple decorators.
+  <br>
+  <a href="https://docs.runqy.com"><strong>Documentation</strong></a> · <a href="https://runqy.com"><strong>Website</strong></a>
+</p>
+
+## Installation
+
+```bash
+pip install runqy-python
+```
+
+## Task Handlers
+
+Create tasks that run on [runqy-worker](https://github.com/publikey/runqy-worker) using simple decorators:
+
+### Simple Task
+
+```python
+from runqy_python import task, run
+
+@task
+def process(payload: dict) -> dict:
+    return {"message": "Hello!", "received": payload}
+
+if __name__ == "__main__":
+    run()
+```
+
+### With Model Loading
+
+For ML inference tasks, use `@load` to load models once at startup:
+
+```python
+from runqy_python import task, load, run
+
+@load
+def setup():
+    """Runs once before ready signal. Return value is passed to @task as ctx."""
+    model = load_heavy_model()  # Load weights, etc.
+    return {"model": model}
+
+@task
+def process(payload: dict, ctx: dict) -> dict:
+    """Process tasks using the loaded model."""
+    prediction = ctx["model"].predict(payload["input"])
+    return {"prediction": prediction}
+
+if __name__ == "__main__":
+    run()
+```
+
+### One-Shot Tasks
+
+For lightweight tasks that don't need to stay loaded in memory, use `run_once()`:
+
+```python
+from runqy_python import task, run_once
+
+@task
+def process(payload: dict) -> dict:
+    return {"result": payload["x"] * 2}
+
+if __name__ == "__main__":
+    run_once()  # Process one task and exit
+```
+
+| Function | Behavior | Use case |
+|----------|----------|----------|
+| `run()` | Loops forever, handles many tasks | ML inference (expensive load) |
+| `run_once()` | Handles ONE task, exits | Lightweight tasks |
+
+## Protocol
+
+The SDK handles the runqy-worker stdin/stdout JSON protocol:
+
+1. **Load phase**: Calls `@load` function (if registered)
+2. **Ready signal**: Sends `{"status": "ready"}` after load completes
+3. **Task input**: Reads JSON from stdin: `{"task_id": "...", "payload": {...}}`
+4. **Response**: Writes JSON to stdout: `{"task_id": "...", "result": {...}, "error": null, "retry": false}`
+
+## Client (Optional)
+
+The SDK also includes a client for enqueuing tasks to a runqy server:
+
+```python
+from runqy_python import RunqyClient
+
+client = RunqyClient("http://localhost:3000", api_key="your-api-key")
+
+# Enqueue a task
+task = client.enqueue("inference_default", {"input": "hello"})
+print(f"Task ID: {task.task_id}")
+
+# Check result
+result = client.get_task(task.task_id)
+print(f"State: {result.state}, Result: {result.result}")
+```
+
+Or use the convenience function:
+
+```python
+from runqy_python import enqueue
+
+task = enqueue(
+    "inference_default",
+    {"input": "hello"},
+    server_url="http://localhost:3000",
+    api_key="your-api-key"
+)
+```
+
+### Client API
+
+**RunqyClient(server_url, api_key, timeout=30)**
+- `server_url`: Base URL of the runqy server
+- `api_key`: API key for authentication
+- `timeout`: Default request timeout in seconds
+
+**client.enqueue(queue, payload, timeout=300)**
+- `queue`: Queue name (e.g., `"inference_default"`)
+- `payload`: Task payload as a dict
+- `timeout`: Task execution timeout in seconds
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`
+
+**client.get_task(task_id)**
+- `task_id`: Task ID from enqueue
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`, `result`, `error`
+
+### Exceptions
+
+- `RunqyError`: Base exception for all client errors
+- `AuthenticationError`: Invalid or missing API key
+- `TaskNotFoundError`: Task ID doesn't exist
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Test task execution
+echo '{"task_id":"t1","payload":{"foo":"bar"}}' | python your_model.py
+
+# Test client import
+python -c "from runqy_python import RunqyClient; print('OK')"
+```

runqy_python-0.2.0/README.md

@@ -0,0 +1,153 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="runqy logo" width="80" height="80">
+</p>
+
+<h1 align="center">runqy-python</h1>
+
+<p align="center">
+  Python SDK for <a href="https://runqy.com">runqy</a> - write distributed task handlers with simple decorators.
+  <br>
+  <a href="https://docs.runqy.com"><strong>Documentation</strong></a> · <a href="https://runqy.com"><strong>Website</strong></a>
+</p>
+
+## Installation
+
+```bash
+pip install runqy-python
+```
+
+## Task Handlers
+
+Create tasks that run on [runqy-worker](https://github.com/publikey/runqy-worker) using simple decorators:
+
+### Simple Task
+
+```python
+from runqy_python import task, run
+
+@task
+def process(payload: dict) -> dict:
+    return {"message": "Hello!", "received": payload}
+
+if __name__ == "__main__":
+    run()
+```
+
+### With Model Loading
+
+For ML inference tasks, use `@load` to load models once at startup:
+
+```python
+from runqy_python import task, load, run
+
+@load
+def setup():
+    """Runs once before ready signal. Return value is passed to @task as ctx."""
+    model = load_heavy_model()  # Load weights, etc.
+    return {"model": model}
+
+@task
+def process(payload: dict, ctx: dict) -> dict:
+    """Process tasks using the loaded model."""
+    prediction = ctx["model"].predict(payload["input"])
+    return {"prediction": prediction}
+
+if __name__ == "__main__":
+    run()
+```
+
+### One-Shot Tasks
+
+For lightweight tasks that don't need to stay loaded in memory, use `run_once()`:
+
+```python
+from runqy_python import task, run_once
+
+@task
+def process(payload: dict) -> dict:
+    return {"result": payload["x"] * 2}
+
+if __name__ == "__main__":
+    run_once()  # Process one task and exit
+```
+
+| Function | Behavior | Use case |
+|----------|----------|----------|
+| `run()` | Loops forever, handles many tasks | ML inference (expensive load) |
+| `run_once()` | Handles ONE task, exits | Lightweight tasks |
+
+## Protocol
+
+The SDK handles the runqy-worker stdin/stdout JSON protocol:
+
+1. **Load phase**: Calls `@load` function (if registered)
+2. **Ready signal**: Sends `{"status": "ready"}` after load completes
+3. **Task input**: Reads JSON from stdin: `{"task_id": "...", "payload": {...}}`
+4. **Response**: Writes JSON to stdout: `{"task_id": "...", "result": {...}, "error": null, "retry": false}`
+
+## Client (Optional)
+
+The SDK also includes a client for enqueuing tasks to a runqy server:
+
+```python
+from runqy_python import RunqyClient
+
+client = RunqyClient("http://localhost:3000", api_key="your-api-key")
+
+# Enqueue a task
+task = client.enqueue("inference_default", {"input": "hello"})
+print(f"Task ID: {task.task_id}")
+
+# Check result
+result = client.get_task(task.task_id)
+print(f"State: {result.state}, Result: {result.result}")
+```
+
+Or use the convenience function:
+
+```python
+from runqy_python import enqueue
+
+task = enqueue(
+    "inference_default",
+    {"input": "hello"},
+    server_url="http://localhost:3000",
+    api_key="your-api-key"
+)
+```
+
+### Client API
+
+**RunqyClient(server_url, api_key, timeout=30)**
+- `server_url`: Base URL of the runqy server
+- `api_key`: API key for authentication
+- `timeout`: Default request timeout in seconds
+
+**client.enqueue(queue, payload, timeout=300)**
+- `queue`: Queue name (e.g., `"inference_default"`)
+- `payload`: Task payload as a dict
+- `timeout`: Task execution timeout in seconds
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`
+
+**client.get_task(task_id)**
+- `task_id`: Task ID from enqueue
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`, `result`, `error`
+
+### Exceptions
+
+- `RunqyError`: Base exception for all client errors
+- `AuthenticationError`: Invalid or missing API key
+- `TaskNotFoundError`: Task ID doesn't exist
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Test task execution
+echo '{"task_id":"t1","payload":{"foo":"bar"}}' | python your_model.py
+
+# Test client import
+python -c "from runqy_python import RunqyClient; print('OK')"
+```

runqy_python-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "runqy-python"
+version = "0.2.0"
+description = "Python SDK for runqy - write distributed task handlers with simple decorators"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = []
+authors = [
+    {name = "Publikey"}
+]
+keywords = ["task-queue", "distributed", "worker", "redis", "async", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Documentation = "https://docs.runqy.com"
+Repository = "https://github.com/Publikey/runqy-python"
+Issues = "https://github.com/Publikey/runqy-python/issues"
+
+[build-system]
+requires = ["setuptools>=61.0,<75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

runqy_python-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runqy_python-0.2.0/src/runqy_python/__init__.py

@@ -0,0 +1,32 @@
+"""runqy-python: Python SDK for runqy - write distributed task handlers with simple decorators."""
+
+# Task execution (for workers)
+from .decorator import task, load
+from .runner import run, run_once
+
+# Client (for enqueuing tasks)
+from .client import (
+    RunqyClient,
+    TaskInfo,
+    RunqyError,
+    AuthenticationError,
+    TaskNotFoundError,
+    enqueue,
+)
+
+__all__ = [
+    # Task execution
+    "task",
+    "load",
+    "run",
+    "run_once",
+    # Client
+    "RunqyClient",
+    "TaskInfo",
+    "RunqyError",
+    "AuthenticationError",
+    "TaskNotFoundError",
+    "enqueue",
+]
+
+__version__ = "0.2.0"

runqy_python-0.2.0/src/runqy_python/client.py

@@ -0,0 +1,240 @@
+"""Client for enqueuing tasks to runqy server."""
+
+import json
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+class RunqyError(Exception):
+    """Base exception for runqy client errors."""
+    pass
+
+
+class AuthenticationError(RunqyError):
+    """Raised when API key is invalid or missing."""
+    pass
+
+
+class TaskNotFoundError(RunqyError):
+    """Raised when a task is not found."""
+    pass
+
+
+@dataclass
+class TaskInfo:
+    """Task information returned from server.
+
+    Attributes:
+        task_id: Unique identifier for the task
+        queue: Queue name the task was submitted to
+        state: Task state (pending, active, completed, etc.)
+        result: Task result data (if completed)
+        error: Error message (if failed)
+        payload: Original task payload
+    """
+    task_id: str
+    queue: str
+    state: str
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    payload: Optional[Dict[str, Any]] = None
+
+
+class RunqyClient:
+    """Client for interacting with runqy server.
+
+    Example:
+        client = RunqyClient("http://localhost:3000", api_key="your-api-key")
+
+        # Enqueue a task
+        task = client.enqueue("inference_default", {"input": "hello"})
+        print(f"Task ID: {task.task_id}")
+
+        # Check result
+        result = client.get_task(task.task_id)
+        print(f"State: {result.state}, Result: {result.result}")
+    """
+
+    def __init__(self, server_url: str, api_key: str, timeout: int = 30):
+        """Initialize the client.
+
+        Args:
+            server_url: Base URL of the runqy server (e.g., "http://localhost:3000")
+            api_key: API key for authentication
+            timeout: Default request timeout in seconds
+        """
+        self.server_url = server_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Make an HTTP request to the server.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: API path (e.g., "/queue/add")
+            data: Request body data (for POST)
+            timeout: Request timeout in seconds
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            RunqyError: For other HTTP errors
+        """
+        url = f"{self.server_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        body = None
+        if data is not None:
+            body = json.dumps(data).encode("utf-8")
+
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
+                response_data = resp.read().decode("utf-8")
+                return json.loads(response_data) if response_data else {}
+        except urllib.error.HTTPError as e:
+            response_body = e.read().decode("utf-8") if e.fp else ""
+
+            if e.code == 401:
+                raise AuthenticationError(f"Authentication failed: {response_body}")
+            elif e.code == 404:
+                raise TaskNotFoundError(f"Task not found: {response_body}")
+            else:
+                raise RunqyError(f"HTTP {e.code}: {response_body}")
+        except urllib.error.URLError as e:
+            raise RunqyError(f"Connection error: {e.reason}")
+
+    def enqueue(
+        self,
+        queue: str,
+        payload: Dict[str, Any],
+        timeout: int = 300
+    ) -> TaskInfo:
+        """Enqueue a task to a queue.
+
+        Args:
+            queue: Queue name (e.g., "inference_default")
+            payload: Task payload data
+            timeout: Task execution timeout in seconds (default: 300)
+
+        Returns:
+            TaskInfo with task_id and initial state
+
+        Raises:
+            AuthenticationError: If API key is invalid
+            RunqyError: For other errors
+
+        Example:
+            task = client.enqueue("inference_default", {"input": "hello"})
+            print(f"Enqueued task: {task.task_id}")
+        """
+        data = {
+            "queue": queue,
+            "timeout": timeout,
+            "data": payload,
+        }
+
+        response = self._request("POST", "/queue/add", data)
+
+        info = response.get("info", {})
+        return TaskInfo(
+            task_id=info.get("id", ""),
+            queue=info.get("queue", queue),
+            state=info.get("state", "pending"),
+            payload=payload,
+        )
+
+    def get_task(self, task_id: str) -> TaskInfo:
+        """Get task status and result.
+
+        Args:
+            task_id: Task ID returned from enqueue()
+
+        Returns:
+            TaskInfo with current state and result (if completed)
+
+        Raises:
+            TaskNotFoundError: If task doesn't exist
+            RunqyError: For other errors
+
+        Example:
+            result = client.get_task(task.task_id)
+            if result.state == "completed":
+                print(f"Result: {result.result}")
+        """
+        response = self._request("GET", f"/queue/{task_id}")
+
+        info = response.get("Info", response.get("info", {}))
+
+        # Parse result if it's a string (JSON)
+        result = info.get("Result", info.get("result"))
+        if isinstance(result, str) and result:
+            try:
+                result = json.loads(result)
+            except json.JSONDecodeError:
+                pass  # Keep as string if not valid JSON
+
+        # Parse payload if it's a string (JSON)
+        payload = info.get("Payload", info.get("payload"))
+        if isinstance(payload, str) and payload:
+            try:
+                payload = json.loads(payload)
+            except json.JSONDecodeError:
+                pass  # Keep as string if not valid JSON
+
+        return TaskInfo(
+            task_id=info.get("ID", info.get("id", task_id)),
+            queue=info.get("Queue", info.get("queue", "")),
+            state=info.get("State", info.get("state", "")),
+            result=result,
+            error=info.get("LastErr", info.get("last_err")),
+            payload=payload,
+        )
+
+
+def enqueue(
+    queue: str,
+    payload: Dict[str, Any],
+    server_url: str,
+    api_key: str,
+    timeout: int = 300
+) -> TaskInfo:
+    """Quick enqueue without creating a client instance.
+
+    Args:
+        queue: Queue name (e.g., "inference_default")
+        payload: Task payload data
+        server_url: Base URL of the runqy server
+        api_key: API key for authentication
+        timeout: Task execution timeout in seconds (default: 300)
+
+    Returns:
+        TaskInfo with task_id and initial state
+
+    Example:
+        from runqy_python import enqueue
+
+        task = enqueue(
+            "inference_default",
+            {"input": "hello"},
+            server_url="http://localhost:3000",
+            api_key="your-api-key"
+        )
+        print(f"Task ID: {task.task_id}")
+    """
+    return RunqyClient(server_url, api_key).enqueue(queue, payload, timeout)

runqy_python-0.2.0/src/runqy_python/decorator.py

@@ -0,0 +1,53 @@
+"""Task decorators for registering handler and load functions."""
+
+_registered_handler = None
+_registered_loader = None
+
+
+def task(func):
+    """Decorator to register a function as the task handler.
+
+    Usage:
+        @task
+        def process(payload: dict) -> dict:
+            return {"result": "..."}
+
+        # With context from @load:
+        @task
+        def process(payload: dict, ctx: dict) -> dict:
+            return ctx["model"].predict(payload)
+    """
+    global _registered_handler
+    _registered_handler = func
+    return func
+
+
+def load(func):
+    """Decorator to register a function that runs once at startup.
+
+    The load function is called before the ready signal is sent.
+    Its return value is passed as the second argument (ctx) to the task handler.
+
+    Usage:
+        @load
+        def setup():
+            model = load_heavy_model()
+            return {"model": model}
+
+        @task
+        def process(payload: dict, ctx: dict) -> dict:
+            return ctx["model"].predict(payload)
+    """
+    global _registered_loader
+    _registered_loader = func
+    return func
+
+
+def get_handler():
+    """Get the registered task handler."""
+    return _registered_handler
+
+
+def get_loader():
+    """Get the registered load function."""
+    return _registered_loader

runqy_python-0.2.0/src/runqy_python/runner.py

@@ -0,0 +1,127 @@
+"""Runner loop for processing tasks from runqy-worker."""
+
+import sys
+import json
+from .decorator import get_handler, get_loader
+
+
+def run():
+    """Main loop: load, ready signal, read tasks, call handler, write responses.
+
+    This function:
+    1. Calls the @load function if registered (for model loading, etc.)
+    2. Sends {"status": "ready"} to signal readiness to runqy-worker
+    3. Reads JSON task requests from stdin (one per line)
+    4. Calls the registered @task handler with the payload (and context if @load was used)
+    5. Writes JSON responses to stdout
+    """
+    handler = get_handler()
+    if handler is None:
+        raise RuntimeError("No task handler registered. Use @task decorator.")
+
+    # Run load function if registered (before ready signal)
+    loader = get_loader()
+    ctx = None
+    if loader is not None:
+        ctx = loader()
+
+    # Ready signal
+    print(json.dumps({"status": "ready"}))
+    sys.stdout.flush()
+
+    # Process tasks from stdin
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        task_id = "unknown"
+        try:
+            task_data = json.loads(line)
+            task_id = task_data.get("task_id", "unknown")
+            payload = task_data.get("payload", {})
+
+            # Call handler with or without context
+            if ctx is not None:
+                result = handler(payload, ctx)
+            else:
+                result = handler(payload)
+
+            response = {
+                "task_id": task_id,
+                "result": result,
+                "error": None,
+                "retry": False
+            }
+        except Exception as e:
+            response = {
+                "task_id": task_id,
+                "result": None,
+                "error": str(e),
+                "retry": False
+            }
+
+        print(json.dumps(response))
+        sys.stdout.flush()
+
+
+def run_once():
+    """Process a single task from stdin and exit.
+
+    Use this for lightweight tasks that don't need to stay loaded in memory.
+
+    Flow:
+    1. Calls @load function if registered
+    2. Sends {"status": "ready"}
+    3. Reads ONE JSON task from stdin
+    4. Calls @task handler
+    5. Writes response to stdout
+    6. Exits
+    """
+    handler = get_handler()
+    if handler is None:
+        raise RuntimeError("No task handler registered. Use @task decorator.")
+
+    # Run load function if registered (before ready signal)
+    loader = get_loader()
+    ctx = None
+    if loader is not None:
+        ctx = loader()
+
+    # Ready signal
+    print(json.dumps({"status": "ready"}))
+    sys.stdout.flush()
+
+    # Read ONE task
+    line = sys.stdin.readline().strip()
+    if not line:
+        return
+
+    task_id = "unknown"
+    try:
+        task_data = json.loads(line)
+        task_id = task_data.get("task_id", "unknown")
+        payload = task_data.get("payload", {})
+
+        # Call handler with or without context
+        if ctx is not None:
+            result = handler(payload, ctx)
+        else:
+            result = handler(payload)
+
+        response = {
+            "task_id": task_id,
+            "result": result,
+            "error": None,
+            "retry": False
+        }
+    except Exception as e:
+        response = {
+            "task_id": task_id,
+            "result": None,
+            "error": str(e),
+            "retry": False
+        }
+
+    print(json.dumps(response))
+    sys.stdout.flush()

runqy_python-0.2.0/src/runqy_python.egg-info/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: runqy-python
+Version: 0.2.0
+Summary: Python SDK for runqy - write distributed task handlers with simple decorators
+Author: Publikey
+Project-URL: Documentation, https://docs.runqy.com
+Project-URL: Repository, https://github.com/Publikey/runqy-python
+Project-URL: Issues, https://github.com/Publikey/runqy-python/issues
+Keywords: task-queue,distributed,worker,redis,async,client
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+<p align="center">
+  <img src="assets/logo.svg" alt="runqy logo" width="80" height="80">
+</p>
+
+<h1 align="center">runqy-python</h1>
+
+<p align="center">
+  Python SDK for <a href="https://runqy.com">runqy</a> - write distributed task handlers with simple decorators.
+  <br>
+  <a href="https://docs.runqy.com"><strong>Documentation</strong></a> · <a href="https://runqy.com"><strong>Website</strong></a>
+</p>
+
+## Installation
+
+```bash
+pip install runqy-python
+```
+
+## Task Handlers
+
+Create tasks that run on [runqy-worker](https://github.com/publikey/runqy-worker) using simple decorators:
+
+### Simple Task
+
+```python
+from runqy_python import task, run
+
+@task
+def process(payload: dict) -> dict:
+    return {"message": "Hello!", "received": payload}
+
+if __name__ == "__main__":
+    run()
+```
+
+### With Model Loading
+
+For ML inference tasks, use `@load` to load models once at startup:
+
+```python
+from runqy_python import task, load, run
+
+@load
+def setup():
+    """Runs once before ready signal. Return value is passed to @task as ctx."""
+    model = load_heavy_model()  # Load weights, etc.
+    return {"model": model}
+
+@task
+def process(payload: dict, ctx: dict) -> dict:
+    """Process tasks using the loaded model."""
+    prediction = ctx["model"].predict(payload["input"])
+    return {"prediction": prediction}
+
+if __name__ == "__main__":
+    run()
+```
+
+### One-Shot Tasks
+
+For lightweight tasks that don't need to stay loaded in memory, use `run_once()`:
+
+```python
+from runqy_python import task, run_once
+
+@task
+def process(payload: dict) -> dict:
+    return {"result": payload["x"] * 2}
+
+if __name__ == "__main__":
+    run_once()  # Process one task and exit
+```
+
+| Function | Behavior | Use case |
+|----------|----------|----------|
+| `run()` | Loops forever, handles many tasks | ML inference (expensive load) |
+| `run_once()` | Handles ONE task, exits | Lightweight tasks |
+
+## Protocol
+
+The SDK handles the runqy-worker stdin/stdout JSON protocol:
+
+1. **Load phase**: Calls `@load` function (if registered)
+2. **Ready signal**: Sends `{"status": "ready"}` after load completes
+3. **Task input**: Reads JSON from stdin: `{"task_id": "...", "payload": {...}}`
+4. **Response**: Writes JSON to stdout: `{"task_id": "...", "result": {...}, "error": null, "retry": false}`
+
+## Client (Optional)
+
+The SDK also includes a client for enqueuing tasks to a runqy server:
+
+```python
+from runqy_python import RunqyClient
+
+client = RunqyClient("http://localhost:3000", api_key="your-api-key")
+
+# Enqueue a task
+task = client.enqueue("inference_default", {"input": "hello"})
+print(f"Task ID: {task.task_id}")
+
+# Check result
+result = client.get_task(task.task_id)
+print(f"State: {result.state}, Result: {result.result}")
+```
+
+Or use the convenience function:
+
+```python
+from runqy_python import enqueue
+
+task = enqueue(
+    "inference_default",
+    {"input": "hello"},
+    server_url="http://localhost:3000",
+    api_key="your-api-key"
+)
+```
+
+### Client API
+
+**RunqyClient(server_url, api_key, timeout=30)**
+- `server_url`: Base URL of the runqy server
+- `api_key`: API key for authentication
+- `timeout`: Default request timeout in seconds
+
+**client.enqueue(queue, payload, timeout=300)**
+- `queue`: Queue name (e.g., `"inference_default"`)
+- `payload`: Task payload as a dict
+- `timeout`: Task execution timeout in seconds
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`
+
+**client.get_task(task_id)**
+- `task_id`: Task ID from enqueue
+- Returns: `TaskInfo` with `task_id`, `queue`, `state`, `result`, `error`
+
+### Exceptions
+
+- `RunqyError`: Base exception for all client errors
+- `AuthenticationError`: Invalid or missing API key
+- `TaskNotFoundError`: Task ID doesn't exist
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e .
+
+# Test task execution
+echo '{"task_id":"t1","payload":{"foo":"bar"}}' | python your_model.py
+
+# Test client import
+python -c "from runqy_python import RunqyClient; print('OK')"
+```

runqy_python-0.2.0/src/runqy_python.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/runqy_python/__init__.py
+src/runqy_python/client.py
+src/runqy_python/decorator.py
+src/runqy_python/runner.py
+src/runqy_python.egg-info/PKG-INFO
+src/runqy_python.egg-info/SOURCES.txt
+src/runqy_python.egg-info/dependency_links.txt
+src/runqy_python.egg-info/top_level.txt

runqy_python-0.2.0/src/runqy_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runqy_python-0.2.0/src/runqy_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+runqy_python