mquark-actionful-client 1.0.2__tar.gz

mquark_actionful_client-1.0.2/.gitignore

@@ -0,0 +1,34 @@
+# .NET
+bin/
+obj/
+*.user
+*.suo
+.vs/
+TestResults/
+*.nupkg
+
+# Rider / JetBrains
+.idea/
+
+# VS Code
+.vscode/
+
+# Environment
+.env
+*.local
+
+# JS/TS
+node_modules/
+dist/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+dist/
+
+# OS
+.DS_Store
+Thumbs.db

mquark_actionful_client-1.0.2/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: mquark-actionful-client
+Version: 1.0.2
+Summary: Official Python client for invoking mQuark Actionful endpoints — single, batch, and pipeline.
+Project-URL: Homepage, https://github.com/m-quark/ActionfulClient
+Project-URL: Repository, https://github.com/m-quark/ActionfulClient
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mquark-actionful-client
+
+Official Python client for invoking [mQuark Actionful](https://mquark.com) endpoints.
+
+See the full documentation and examples at [github.com/m-quark/ActionfulClient](https://github.com/m-quark/ActionfulClient).
+
+## Installation
+
+```sh
+pip install mquark-actionful-client
+```
+
+Requires Python 3.10+ and `httpx`.
+
+## Quick start
+
+```python
+from mquark_actionful import ActionfulClient, ActionfulClientOptions
+
+client = ActionfulClient(ActionfulClientOptions(
+    endpoint_url="https://...",
+    access_token="...",
+    access_secret="...",
+))
+
+# Single invocation
+result = await client.invoke({"orderId": 42})
+
+# Batch
+results = await client.invoke_batch([item1, item2, item3])
+
+# Stream
+async for r in client.stream_batch(items):
+    if r.is_success:
+        print(r.output)
+
+# Async pipeline
+async for result in client.process(async_item_stream()):
+    await sink.write(result)
+
+# Close when done
+await client.aclose()
+# or use as context manager: async with ActionfulClient(...) as client: ...
+```
+
+## License
+
+MIT

mquark_actionful_client-1.0.2/README.md

@@ -0,0 +1,48 @@
+# mquark-actionful-client
+
+Official Python client for invoking [mQuark Actionful](https://mquark.com) endpoints.
+
+See the full documentation and examples at [github.com/m-quark/ActionfulClient](https://github.com/m-quark/ActionfulClient).
+
+## Installation
+
+```sh
+pip install mquark-actionful-client
+```
+
+Requires Python 3.10+ and `httpx`.
+
+## Quick start
+
+```python
+from mquark_actionful import ActionfulClient, ActionfulClientOptions
+
+client = ActionfulClient(ActionfulClientOptions(
+    endpoint_url="https://...",
+    access_token="...",
+    access_secret="...",
+))
+
+# Single invocation
+result = await client.invoke({"orderId": 42})
+
+# Batch
+results = await client.invoke_batch([item1, item2, item3])
+
+# Stream
+async for r in client.stream_batch(items):
+    if r.is_success:
+        print(r.output)
+
+# Async pipeline
+async for result in client.process(async_item_stream()):
+    await sink.write(result)
+
+# Close when done
+await client.aclose()
+# or use as context manager: async with ActionfulClient(...) as client: ...
+```
+
+## License
+
+MIT

mquark_actionful_client-1.0.2/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mquark-actionful-client"
+version = "1.0.2"
+description = "Official Python client for invoking mQuark Actionful endpoints — single, batch, and pipeline."
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/m-quark/ActionfulClient"
+Repository = "https://github.com/m-quark/ActionfulClient"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mquark_actionful"]

mquark_actionful_client-1.0.2/src/mquark_actionful/__init__.py

@@ -0,0 +1,24 @@
+from ._client import ActionfulClient, Pipeline
+from ._types import (
+    ActionfulClientOptions,
+    ActionfulError,
+    BatchOptions,
+    InvocationJob,
+    InvocationResult,
+    InvocationStatus,
+    InvocationTicket,
+    PipelineOptions,
+)
+
+__all__ = [
+    "ActionfulClient",
+    "ActionfulClientOptions",
+    "ActionfulError",
+    "BatchOptions",
+    "InvocationJob",
+    "InvocationResult",
+    "InvocationStatus",
+    "InvocationTicket",
+    "Pipeline",
+    "PipelineOptions",
+]

mquark_actionful_client-1.0.2/src/mquark_actionful/_client.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+from datetime import datetime, timezone
+from typing import Any, AsyncGenerator, AsyncIterator, Iterable
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from ._types import (
+    ActionfulClientOptions,
+    ActionfulError,
+    BatchOptions,
+    InvocationJob,
+    InvocationResult,
+    InvocationStatus,
+    InvocationTicket,
+    PipelineOptions,
+)
+
+# Sent on submit() to force an immediate 202 (internal optimisation, not part of the public contract).
+_TIMEOUT_HEADER = "Mq-Timeout-Seconds"
+
+_SENTINEL = object()
+
+
+class ActionfulClient:
+    """Client for invoking a single published mQuark Actionful endpoint."""
+
+    def __init__(
+        self,
+        options: ActionfulClientOptions,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._endpoint_url = options.endpoint_url
+        self._poll_interval = options.poll_interval
+        self._http = http_client or httpx.AsyncClient(
+            auth=(options.access_token, options.access_secret)
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> ActionfulClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    # ── Layer 1 · Raw async ──────────────────────────────────────────────────
+
+    async def submit(self, input: Any) -> InvocationTicket:
+        """Submits a payload and returns a ticket immediately (always 202)."""
+        response = await self._http.post(
+            self._endpoint_url,
+            content=_serialise(input),
+            headers={"Content-Type": "application/json", _TIMEOUT_HEADER: "0"},
+        )
+        _ensure_success(response)
+        return _parse_ticket(response)
+
+    async def get_job(self, ticket_or_url: InvocationTicket | str) -> InvocationJob:
+        """Polls once and returns the job's current state."""
+        poll_url = ticket_or_url if isinstance(ticket_or_url, str) else ticket_or_url.poll_url
+        response = await self._http.get(poll_url)
+        _ensure_success(response)
+
+        job_id = _extract_job_id(poll_url)
+        if response.status_code == 200:
+            return InvocationJob(
+                job_id=job_id,
+                status=InvocationStatus.SUCCEEDED,
+                result_json=response.text,
+            )
+        return InvocationJob(job_id=job_id, status=InvocationStatus.RUNNING)
+
+    # ── Layer 2 · Invoke and wait ─────────────────────────────────────────
+
+    async def invoke_raw(self, payload: str) -> str:
+        """Submits payload, polls until completion, returns the raw result string."""
+        response = await self._http.post(
+            self._endpoint_url,
+            content=payload,
+            headers={"Content-Type": "application/json"},
+        )
+        _ensure_success(response)
+
+        if response.status_code == 200:
+            return response.text
+
+        ticket = _parse_ticket(response)
+        return await self._poll_until_complete(ticket.poll_url)
+
+    async def invoke(self, input: Any) -> Any:
+        """Serialises input, invokes the endpoint, returns the deserialised result (dict/list/primitive)."""
+        raw = await self.invoke_raw(_serialise(input))
+        return _deserialise(raw)
+
+    # ── Layer 3 · Batch ───────────────────────────────────────────────────
+
+    async def invoke_batch(
+        self,
+        inputs: Iterable[Any],
+        options: BatchOptions | None = None,
+    ) -> list[InvocationResult[Any]]:
+        """Processes all inputs and returns results when everything completes."""
+        results: list[InvocationResult[Any]] = []
+        async for r in self.stream_batch(inputs, options):
+            results.append(r)
+        return results
+
+    async def stream_batch(
+        self,
+        inputs: Iterable[Any],
+        options: BatchOptions | None = None,
+    ) -> AsyncGenerator[InvocationResult[Any], None]:
+        """Processes inputs concurrently, yielding results as each completes."""
+        opts = options or BatchOptions()
+        out: asyncio.Queue[Any] = asyncio.Queue(maxsize=opts.output_buffer_capacity)
+        sem = asyncio.Semaphore(opts.max_concurrency)
+        stop = asyncio.Event()
+
+        async def worker(item: Any) -> None:
+            result = await self._invoke_one(item)
+            if not result.is_success and opts.stop_on_first_failure:
+                stop.set()
+            await out.put(result)
+            sem.release()
+
+        async def producer() -> None:
+            tasks: list[asyncio.Task[None]] = []
+            for item in inputs:
+                if stop.is_set():
+                    break
+                await sem.acquire()
+                tasks.append(asyncio.create_task(worker(item)))
+            await asyncio.gather(*tasks, return_exceptions=True)
+            await out.put(_SENTINEL)
+
+        producer_task = asyncio.create_task(producer())
+
+        while True:
+            item = await out.get()
+            if item is _SENTINEL:
+                break
+            yield item
+
+        await producer_task
+
+    # ── Layer 4 · Pipeline ────────────────────────────────────────────────
+
+    async def process(
+        self,
+        inputs: AsyncIterator[Any],
+        options: PipelineOptions | None = None,
+    ) -> AsyncGenerator[InvocationResult[Any], None]:
+        """Processes an async-iterable stream, yielding results as each completes."""
+        opts = options or PipelineOptions()
+        out: asyncio.Queue[Any] = asyncio.Queue(maxsize=opts.output_buffer_capacity)
+        sem = asyncio.Semaphore(opts.max_concurrency)
+
+        async def worker(item: Any) -> None:
+            result = await self._invoke_one(item)
+            await out.put(result)
+            sem.release()
+
+        async def producer() -> None:
+            tasks: list[asyncio.Task[None]] = []
+            async for item in inputs:
+                await sem.acquire()
+                tasks.append(asyncio.create_task(worker(item)))
+            await asyncio.gather(*tasks, return_exceptions=True)
+            await out.put(_SENTINEL)
+
+        producer_task = asyncio.create_task(producer())
+
+        while True:
+            item = await out.get()
+            if item is _SENTINEL:
+                break
+            yield item
+
+        await producer_task
+
+    def create_pipeline(self, options: PipelineOptions | None = None) -> Pipeline:
+        """Creates a long-running pipeline with explicit push/complete/iterate control."""
+        return Pipeline(self._invoke_one, options)
+
+    # ── Internal ─────────────────────────────────────────────────────────────
+
+    async def _poll_until_complete(self, poll_url: str) -> str:
+        while True:
+            response = await self._http.get(poll_url)
+            _ensure_success(response)
+
+            if response.status_code == 200:
+                return response.text
+
+            await asyncio.sleep(_poll_wait(response, self._poll_interval))
+
+    async def _invoke_one(self, item: Any) -> InvocationResult[Any]:
+        ticket = InvocationTicket(job_id="unknown", poll_url="", submitted_at=datetime.now(timezone.utc))
+        try:
+            ticket = await self.submit(item)
+            result_json = await self._poll_until_complete(ticket.poll_url)
+            return InvocationResult(ticket=ticket, output=_deserialise(result_json), error=None)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            return InvocationResult(ticket=ticket, output=None, error=str(exc))
+
+
+class Pipeline:
+    """Long-running pipeline with explicit push/complete/iterate control.
+
+    Create via ``client.create_pipeline()`` inside an async context. Push items
+    with ``await push()``, signal end with ``complete()``, and consume results
+    with ``async for``.
+    """
+
+    def __init__(
+        self,
+        invoke_fn: Any,
+        options: PipelineOptions | None = None,
+    ) -> None:
+        self._invoke_fn = invoke_fn
+        self._opts = options or PipelineOptions()
+        self._input: asyncio.Queue[Any] | None = None
+        self._output: asyncio.Queue[Any] | None = None
+        self._task: asyncio.Task[None] | None = None
+
+    def _ensure_started(self) -> None:
+        if self._task is None:
+            self._input = asyncio.Queue(maxsize=self._opts.input_buffer_capacity)
+            self._output = asyncio.Queue(maxsize=self._opts.output_buffer_capacity)
+            self._task = asyncio.create_task(self._run())
+
+    async def push(self, item: Any) -> None:
+        """Sends an item to the pipeline. Blocks when the input buffer is full."""
+        self._ensure_started()
+        assert self._input is not None
+        await self._input.put(item)
+
+    def complete(self) -> None:
+        """Signals that no more items will be pushed. Must be called exactly once."""
+        self._ensure_started()
+        assert self._input is not None
+        self._input.put_nowait(_SENTINEL)
+
+    def __aiter__(self) -> Pipeline:
+        return self
+
+    async def __anext__(self) -> InvocationResult[Any]:
+        self._ensure_started()
+        assert self._output is not None
+        result = await self._output.get()
+        if result is _SENTINEL:
+            raise StopAsyncIteration
+        return result
+
+    async def _run(self) -> None:
+        assert self._input is not None
+        assert self._output is not None
+        sem = asyncio.Semaphore(self._opts.max_concurrency)
+        tasks: list[asyncio.Task[None]] = []
+
+        while True:
+            item = await self._input.get()
+            if item is _SENTINEL:
+                break
+            await sem.acquire()
+
+            async def worker(i: Any, s: asyncio.Semaphore = sem) -> None:
+                result = await self._invoke_fn(i)
+                await self._output.put(result)  # type: ignore[union-attr]
+                s.release()
+
+            tasks.append(asyncio.create_task(worker(item)))
+
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await self._output.put(_SENTINEL)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _serialise(input: Any) -> str:
+    if isinstance(input, str):
+        return input
+    if dataclasses.is_dataclass(input) and not isinstance(input, type):
+        return json.dumps(dataclasses.asdict(input))
+    return json.dumps(input)
+
+
+def _deserialise(json_str: str) -> Any:
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError:
+        return json_str
+
+
+def _parse_ticket(response: httpx.Response) -> InvocationTicket:
+    location = response.headers.get("location") or response.headers.get("Location")
+    if not location:
+        raise ActionfulError(response.status_code, "202 response missing Location header")
+    if not location.startswith("http"):
+        location = urljoin(str(response.url), location)
+    return InvocationTicket(
+        job_id=_extract_job_id(location),
+        poll_url=location,
+        submitted_at=datetime.now(timezone.utc),
+    )
+
+
+def _extract_job_id(url: str) -> str:
+    path = urlparse(url).path.rstrip("/")
+    return path.rsplit("/", 1)[-1]
+
+
+def _ensure_success(response: httpx.Response) -> None:
+    if response.status_code in (200, 202):
+        return
+    retry_after: int | None = None
+    if response.status_code == 429:
+        ra = response.headers.get("retry-after", "")
+        if ra.isdigit():
+            retry_after = int(ra)
+    raise ActionfulError(
+        status_code=response.status_code,
+        body=response.text.strip(),
+        retry_after=retry_after,
+    )
+
+
+def _poll_wait(response: httpx.Response, floor: float) -> float:
+    ra = response.headers.get("retry-after", "")
+    if ra.isdigit():
+        return max(floor, float(ra))
+    return floor

mquark_actionful_client-1.0.2/src/mquark_actionful/_types.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class InvocationStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (self.SUCCEEDED, self.FAILED, self.CANCELLED)
+
+
+@dataclass(frozen=True)
+class InvocationTicket:
+    job_id: str
+    poll_url: str
+    submitted_at: datetime
+
+
+@dataclass(frozen=True)
+class InvocationJob:
+    job_id: str
+    status: InvocationStatus
+    result_json: str | None = None
+    error: str | None = None
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status.is_terminal
+
+
+@dataclass(frozen=True)
+class InvocationResult(Generic[T]):
+    ticket: InvocationTicket
+    output: T | None
+    error: str | None
+
+    @property
+    def is_success(self) -> bool:
+        return self.error is None
+
+
+class ActionfulError(Exception):
+    """Raised for non-2xx HTTP responses."""
+
+    def __init__(self, status_code: int, body: str, retry_after: int | None = None) -> None:
+        super().__init__(f"HTTP {status_code}: {body}")
+        self.status_code = status_code
+        self.body = body
+        self.retry_after = retry_after  # seconds; populated on 429
+
+
+@dataclass
+class ActionfulClientOptions:
+    """Configuration for ActionfulClient."""
+
+    endpoint_url: str
+    access_token: str
+    access_secret: str
+    # Floor for poll wait; server Retry-After wins when higher.
+    poll_interval: float = 2.0
+
+    def __post_init__(self) -> None:
+        if not self.endpoint_url:
+            raise ValueError("endpoint_url is required")
+        if not self.access_token:
+            raise ValueError("access_token is required")
+        if not self.access_secret:
+            raise ValueError("access_secret is required")
+
+
+@dataclass
+class BatchOptions:
+    max_concurrency: int = 10
+    stop_on_first_failure: bool = False
+    output_buffer_capacity: int = 1000
+
+
+@dataclass
+class PipelineOptions:
+    max_concurrency: int = 10
+    input_buffer_capacity: int = 1000
+    output_buffer_capacity: int = 1000

mquark_actionful_client-1.0.2/tests/conftest.py

@@ -0,0 +1,30 @@
+import httpx
+import pytest
+
+from mquark_actionful import ActionfulClient, ActionfulClientOptions
+
+ENDPOINT = "https://api.test/endpoint"
+JOB_URL = "https://api.test/jobs/abc123"
+
+
+def make_client(poll_interval: float = 0.001) -> ActionfulClient:
+    return ActionfulClient(
+        ActionfulClientOptions(
+            endpoint_url=ENDPOINT,
+            access_token="tok",
+            access_secret="sec",
+            poll_interval=poll_interval,
+        )
+    )
+
+
+def resp_202(job_url: str = JOB_URL) -> httpx.Response:
+    return httpx.Response(202, headers={"Location": job_url})
+
+
+def resp_200(body: str = '{"score": 0.9}') -> httpx.Response:
+    return httpx.Response(200, text=body)
+
+
+def resp_error(status: int = 500, body: str = "internal error") -> httpx.Response:
+    return httpx.Response(status, text=body)

mquark_actionful_client-1.0.2/tests/test_batch.py

@@ -0,0 +1,102 @@
+import asyncio
+import httpx
+import respx
+
+from .conftest import ENDPOINT, JOB_URL, make_client, resp_200, resp_202, resp_error
+
+
+async def test_invoke_batch_all_succeed():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=resp_200('{"score": 0.5}'))
+        async with make_client() as client:
+            results = await client.invoke_batch([{"id": 1}, {"id": 2}, {"id": 3}])
+
+    assert len(results) == 3
+    assert all(r.is_success for r in results)
+    assert all(r.output == {"score": 0.5} for r in results)
+
+
+async def test_invoke_batch_partial_failure():
+    call_count = 0
+
+    def post_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        if call_count % 2 == 0:
+            return resp_error(500, "forced error")
+        return resp_202("https://api.test/jobs/ok")
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(side_effect=post_side_effect)
+        respx.get("https://api.test/jobs/ok").mock(return_value=resp_200('{"score": 0.5}'))
+        async with make_client() as client:
+            results = await client.invoke_batch([{"id": i} for i in range(4)])
+
+    assert len(results) == 4
+    successes = [r for r in results if r.is_success]
+    failures = [r for r in results if not r.is_success]
+    assert len(successes) > 0
+    assert len(failures) > 0
+
+
+async def test_stream_batch_yields_as_complete():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=resp_200('{"score": 0.3}'))
+        async with make_client() as client:
+            received = []
+            async for r in client.stream_batch([{"id": 1}, {"id": 2}]):
+                received.append(r)
+
+    assert len(received) == 2
+    assert all(r.is_success for r in received)
+
+
+async def test_stream_batch_stop_on_first_failure():
+    from mquark_actionful import BatchOptions
+
+    call_count = 0
+
+    def post_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            return resp_error(500, "first failure")
+        return resp_202()
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(side_effect=post_side_effect)
+        respx.get(JOB_URL).mock(return_value=resp_200())
+        opts = BatchOptions(max_concurrency=1, stop_on_first_failure=True)
+        async with make_client() as client:
+            results = []
+            async for r in client.stream_batch([{"id": i} for i in range(50)], opts):
+                results.append(r)
+
+    assert len(results) < 50
+
+
+async def test_batch_respects_max_concurrency():
+    """No more than MaxConcurrency requests should be in flight at the same time."""
+    from mquark_actionful import BatchOptions
+
+    in_flight = 0
+    max_seen = 0
+
+    async def post_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal in_flight, max_seen
+        in_flight += 1
+        max_seen = max(max_seen, in_flight)
+        await asyncio.sleep(0.01)
+        in_flight -= 1
+        return resp_202()
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(side_effect=post_side_effect)
+        respx.get(JOB_URL).mock(return_value=resp_200())
+        opts = BatchOptions(max_concurrency=3)
+        async with make_client() as client:
+            await client.invoke_batch([{"id": i} for i in range(10)], opts)
+
+    assert max_seen <= 3

mquark_actionful_client-1.0.2/tests/test_invoke.py

@@ -0,0 +1,92 @@
+import asyncio
+import httpx
+import pytest
+import respx
+
+from .conftest import ENDPOINT, JOB_URL, make_client, resp_200, resp_202
+
+
+async def test_invoke_raw_fast_path_200():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_200('{"score": 0.9}'))
+        async with make_client() as client:
+            result = await client.invoke_raw('{"id": 1}')
+
+    assert result == '{"score": 0.9}'
+
+
+async def test_invoke_raw_async_path_polls_until_200():
+    poll_count = 0
+
+    def poll_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal poll_count
+        poll_count += 1
+        if poll_count < 3:
+            return httpx.Response(202, headers={"Retry-After": "0"})
+        return resp_200('{"score": 0.5}')
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(side_effect=poll_side_effect)
+        async with make_client() as client:
+            result = await client.invoke_raw('{"id": 1}')
+
+    assert result == '{"score": 0.5}'
+    assert poll_count == 3
+
+
+async def test_invoke_returns_dict():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_200('{"score": 0.85}'))
+        async with make_client() as client:
+            result = await client.invoke({"id": 1})
+
+    assert result == {"score": 0.85}
+
+
+async def test_invoke_returns_string_for_plain_text():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_200("plain text result"))
+        async with make_client() as client:
+            result = await client.invoke_raw("plain text result")
+
+    assert result == "plain text result"
+
+
+async def test_invoke_respects_retry_after():
+    """Server Retry-After wins when higher than PollInterval."""
+    poll_times: list[float] = []
+    poll_count = 0
+
+    def poll_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal poll_count
+        poll_count += 1
+        poll_times.append(asyncio.get_event_loop().time())
+        if poll_count < 2:
+            return httpx.Response(202, headers={"Retry-After": "0"})
+        return resp_200('{"done": true}')
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(side_effect=poll_side_effect)
+        async with make_client(poll_interval=0.001) as client:
+            await client.invoke_raw('{}')
+
+    assert poll_count == 2
+
+
+async def test_invoke_cancellation():
+    async def slow_poll(request: httpx.Request) -> httpx.Response:
+        await asyncio.sleep(10)
+        return resp_200()
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(side_effect=slow_poll)
+
+        async with make_client() as client:
+            with pytest.raises(asyncio.CancelledError):
+                task = asyncio.create_task(client.invoke_raw('{}'))
+                await asyncio.sleep(0.01)
+                task.cancel()
+                await task

mquark_actionful_client-1.0.2/tests/test_pipeline.py

@@ -0,0 +1,108 @@
+import asyncio
+import httpx
+import respx
+
+from .conftest import ENDPOINT, JOB_URL, make_client, resp_200, resp_202
+
+
+async def test_process_streams_results():
+    async def input_stream():
+        for i in range(3):
+            yield {"id": i}
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=resp_200('{"score": 0.3}'))
+        async with make_client() as client:
+            results = []
+            async for r in client.process(input_stream()):
+                results.append(r)
+
+    assert len(results) == 3
+    assert all(r.is_success for r in results)
+
+
+async def test_pipeline_push_and_iterate():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=resp_200('{"score": 0.6}'))
+        async with make_client() as client:
+            pipeline = client.create_pipeline()
+
+            async def producer() -> None:
+                for i in range(5):
+                    await pipeline.push({"id": i})
+                pipeline.complete()
+
+            asyncio.create_task(producer())
+
+            results = []
+            async for r in pipeline:
+                results.append(r)
+
+    assert len(results) == 5
+    assert all(r.is_success for r in results)
+    assert all(r.output == {"score": 0.6} for r in results)
+
+
+async def test_pipeline_errors_captured_per_item():
+    from mquark_actionful import PipelineOptions
+
+    call_count = 0
+
+    def post_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        if call_count % 2 == 0:
+            return httpx.Response(500, text="forced error")
+        return resp_202("https://api.test/jobs/ok")
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(side_effect=post_side_effect)
+        respx.get("https://api.test/jobs/ok").mock(return_value=resp_200())
+        async with make_client() as client:
+            pipeline = client.create_pipeline(PipelineOptions(max_concurrency=1))
+
+            async def producer() -> None:
+                for i in range(4):
+                    await pipeline.push({"id": i})
+                pipeline.complete()
+
+            asyncio.create_task(producer())
+
+            results = []
+            async for r in pipeline:
+                results.append(r)
+
+    assert len(results) == 4
+    assert any(r.is_success for r in results)
+    assert any(not r.is_success for r in results)
+
+
+async def test_process_respects_max_concurrency():
+    from mquark_actionful import PipelineOptions
+
+    in_flight = 0
+    max_seen = 0
+
+    async def post_side_effect(request: httpx.Request) -> httpx.Response:
+        nonlocal in_flight, max_seen
+        in_flight += 1
+        max_seen = max(max_seen, in_flight)
+        await asyncio.sleep(0.01)
+        in_flight -= 1
+        return resp_202()
+
+    async def input_stream():
+        for i in range(10):
+            yield {"id": i}
+
+    with respx.mock:
+        respx.post(ENDPOINT).mock(side_effect=post_side_effect)
+        respx.get(JOB_URL).mock(return_value=resp_200())
+        opts = PipelineOptions(max_concurrency=3)
+        async with make_client() as client:
+            async for _ in client.process(input_stream(), opts):
+                pass
+
+    assert max_seen <= 3

mquark_actionful_client-1.0.2/tests/test_submit.py

@@ -0,0 +1,102 @@
+import httpx
+import pytest
+import respx
+
+from mquark_actionful import ActionfulError, InvocationStatus
+
+from .conftest import ENDPOINT, JOB_URL, make_client, resp_200, resp_202, resp_error
+
+
+async def test_submit_returns_ticket():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        async with make_client() as client:
+            ticket = await client.submit({"id": 1})
+
+    assert ticket.job_id == "abc123"
+    assert ticket.poll_url == JOB_URL
+
+
+async def test_submit_serialises_dict():
+    with respx.mock:
+        route = respx.post(ENDPOINT).mock(return_value=resp_202())
+        async with make_client() as client:
+            await client.submit({"order": 42})
+
+    assert route.called
+    import json
+    assert json.loads(route.calls[0].request.content) == {"order": 42}
+
+
+async def test_submit_passes_raw_json_string():
+    with respx.mock:
+        route = respx.post(ENDPOINT).mock(return_value=resp_202())
+        async with make_client() as client:
+            await client.submit('{"raw": true}')
+
+    body = route.calls[0].request.content
+    assert b'"raw": true' in body
+
+
+async def test_get_job_running_on_202():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=httpx.Response(202, headers={"Retry-After": "0"}))
+        async with make_client() as client:
+            ticket = await client.submit({"id": 1})
+            job = await client.get_job(ticket)
+
+    assert job.status == InvocationStatus.RUNNING
+    assert not job.is_terminal
+
+
+async def test_get_job_succeeded_on_200():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_202())
+        respx.get(JOB_URL).mock(return_value=resp_200('{"score": 0.7}'))
+        async with make_client() as client:
+            ticket = await client.submit({"id": 1})
+            job = await client.get_job(ticket)
+
+    assert job.status == InvocationStatus.SUCCEEDED
+    assert job.result_json == '{"score": 0.7}'
+    assert job.is_terminal
+
+
+async def test_get_job_accepts_poll_url_string():
+    with respx.mock:
+        respx.get(JOB_URL).mock(return_value=resp_200())
+        async with make_client() as client:
+            job = await client.get_job(JOB_URL)
+
+    assert job.status == InvocationStatus.SUCCEEDED
+
+
+async def test_submit_raises_on_4xx():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=resp_error(400, "bad input"))
+        async with make_client() as client:
+            with pytest.raises(ActionfulError) as exc_info:
+                await client.submit({"id": 1})
+
+    assert exc_info.value.status_code == 400
+    assert exc_info.value.body == "bad input"
+
+
+async def test_submit_raises_with_retry_after_on_429():
+    with respx.mock:
+        respx.post(ENDPOINT).mock(return_value=httpx.Response(
+            429, text="rate limited", headers={"Retry-After": "30"}
+        ))
+        async with make_client() as client:
+            with pytest.raises(ActionfulError) as exc_info:
+                await client.submit({"id": 1})
+
+    assert exc_info.value.status_code == 429
+    assert exc_info.value.retry_after == 30
+
+
+async def test_missing_endpoint_url_raises():
+    with pytest.raises(ValueError, match="endpoint_url"):
+        from mquark_actionful import ActionfulClientOptions
+        ActionfulClientOptions(endpoint_url="", access_token="t", access_secret="s")