async-task-api-worker 0.1.0rc2__tar.gz → 0.1.0rc5__tar.gz

async_task_api_worker-0.1.0rc5/.gitignore

@@ -0,0 +1,52 @@
+.venv
+.env
+.coverage
+.pytest_cache/
+__pycache__
+htmlcov/
+junit.xml
+.vscode/
+.ruff_cache
+node_modules/
+package-lock.json
+*.egg-info/
+dist/
+build/
+*.log
+*.pot
+*.pyc
+.scratch
+# helm/charts/ is deliberately NOT ignored: ArgoCD cannot reach external repositories.
+.DS_Store
+demo.db
+coverage.xml
+
+# Sorties locales sensibles (audit, homologation, tests d'intrusion) — ne pas committer
+private/
+
+# Secrets et matériel cryptographique
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa*
+id_ed25519*
+*.kubeconfig
+kubeconfig*
+*.tfstate
+*.tfstate.*
+secrets/
+*.secret
+
+# Dumps et sauvegardes
+*.sql.gz
+*.dump
+*.bak-*
+
+# Assistant configuration is local to each machine: nothing under .claude/ is tracked.
+.claude/
+
+# Private working plans and notes: never committed.
+docs/workers-v2/

{async_task_api_worker-0.1.0rc2 → async_task_api_worker-0.1.0rc5}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.1.0-rc.5](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.4...async-task-api-worker-v0.1.0-rc.5) (2026-10-26)
+
+
+### Bug Fixes
+
+* **sdk:** name the wait that timed out in conformance failures ([73cc271](https://github.com/IA-Generative/async-api/commit/73cc271d67950b5b272740af291b085d1b7e1546))
+
+## [0.1.0-rc.4](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.3...async-task-api-worker-v0.1.0-rc.4) (2026-10-26)
+
+
+### Features
+
+* **sdk:** add the conformance command and the pytest plugin ([03a1c7b](https://github.com/IA-Generative/async-api/commit/03a1c7b06d45ecfe4410d5cfa3d9b254a4c7dad0))
+* **sdk:** add the conformance suite and its reference worker ([d3e9fc7](https://github.com/IA-Generative/async-api/commit/d3e9fc791e5847e7c42f2b26ef153993545b0430))
+* **sdk:** add the llm extra ([d650023](https://github.com/IA-Generative/async-api/commit/d650023d958890dede1b75d86e60039da55332be))
+* **sdk:** add the manifest and spec commands ([700331c](https://github.com/IA-Generative/async-api/commit/700331c14dccf0625c6897decb4b525e3946c802))
+* **sdk:** add the manifest of a service, derived from the input model ([8ab58d6](https://github.com/IA-Generative/async-api/commit/8ab58d6612a3bd718d7581cccccd595f9e6f6b47))
+* **sdk:** add the quorum queue emulator, the fake API and the fake listener ([8706837](https://github.com/IA-Generative/async-api/commit/8706837238897aefeb5679b8f35ea4ce7931b2bf))
+* **sdk:** add the s3 extra ([5ac8168](https://github.com/IA-Generative/async-api/commit/5ac81689d4c8974d51ddd849fe8cb8f5a1863238))
+* **sdk:** generate the AsyncAPI 3.0 document of the protocol from its models ([749207b](https://github.com/IA-Generative/async-api/commit/749207bc797b475f09bac3e5c93480fa4ad58c20))
+
+
+### Documentation
+
+* **sdk:** add the guides to write a worker and to register a service ([c5a6fe8](https://github.com/IA-Generative/async-api/commit/c5a6fe8bdc116a2a0a30dfbc3766cd19efd4d89e))
+* **sdk:** document the conformance kit ([ae0bc9c](https://github.com/IA-Generative/async-api/commit/ae0bc9c2dc0bd55b732c4d1396cb55f33e0c296d))
+* **sdk:** document the protocol, its versioning and the manifest and spec commands ([3e8d510](https://github.com/IA-Generative/async-api/commit/3e8d510a84387a46c81548c2eb3195c8b3b5ce97))
+* **sdk:** document the s3 and llm extras ([e3bc270](https://github.com/IA-Generative/async-api/commit/e3bc2704a5acc520972dfdcc7ff1bb20180361e6))
+
+## [0.1.0-rc.3](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.2...async-task-api-worker-v0.1.0-rc.3) (2026-10-23)
+
+
+### Bug Fixes
+
+* **sdk:** close an already closed channel quietly and tie the close budgets together ([51e0281](https://github.com/IA-Generative/async-api/commit/51e0281dfe7ea22686f0967d4c8ce55efa470d0e))
+* **sdk:** name the invalid settings instead of quoting pydantic's text about them ([df6c747](https://github.com/IA-Generative/async-api/commit/df6c7475464600f31f767997269d3f86b1cf432e))
+* **sdk:** treat a pydantic validation error in a startup hook as a configuration error ([5e98af1](https://github.com/IA-Generative/async-api/commit/5e98af109a027fc2903a3f98d5d0028f936efbba))
+
 ## [0.1.0-rc.2](https://github.com/IA-Generative/async-api/compare/async-task-api-worker-v0.1.0-rc.1...async-task-api-worker-v0.1.0-rc.2) (2026-10-23)
 
 

async_task_api_worker-0.1.0rc5/PKG-INFO

@@ -0,0 +1,525 @@
+Metadata-Version: 2.5
+Name: async-task-api-worker
+Version: 0.1.0-rc.5
+Summary: SDK to write workers for the AsyncTaskAPI platform: protocol models, runtime and conformance kit.
+Project-URL: Repository, https://github.com/IA-Generative/async-api
+License: MIT
+License-File: LICENSE
+Keywords: async-api,rabbitmq,sdk,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aio-pika>=9.5.5
+Requires-Dist: prometheus-client>=0.22.1
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.10
+Provides-Extra: llm
+Requires-Dist: httpx>=0.28.1; extra == 'llm'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.43.118; extra == 's3'
+Provides-Extra: testing
+Requires-Dist: pytest>=9.1.1; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# async-task-api-worker
+
+SDK to write workers for the AsyncTaskAPI platform.
+
+This is a work in progress: the package ships the protocol models (inbound envelope decoder and the byte-exact
+outbound message encoder), the error types, the settings, the runtime engine with the `Worker` definition API, the
+RabbitMQ transport, the process lifecycle (graceful drain), the probes, the metrics and the JSON logs. The conformance
+suite is part of the testing kit below; the `[s3]` and `[llm]` extras are described below.
+
+## Declaring a worker
+
+```python
+from pydantic import BaseModel, Field
+
+from async_task_api_worker import TaskContext, Worker
+
+
+class Input(BaseModel):
+    text: str = Field(min_length=1, max_length=100_000)
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+```
+
+- `async def` handlers run on the event loop; `def` handlers (with a `SyncTaskContext`) run in a thread pool. The
+  context parameter must be annotated exactly `TaskContext` or `SyncTaskContext` (an identity check: no subclass or
+  `Annotated` wrapper). Hooks and probes (`on_startup`, `on_shutdown`, `readiness_probe`) must be `async def`.
+- The input and output models are read from the annotations. Exactly one task per worker.
+- Raise `FatalError(code, message)` to fail a task with a code the client can match, `RetryableError` for a
+  transient failure. Any other exception is reported as `INTERNAL_ERROR` without its text.
+- `ctx.progress(fraction, payload)` reports the **latest state** of the task, not an event stream: updates are
+  throttled (at most one per `WORKER_PROGRESS_MIN_INTERVAL_S`, default 1 s), a newer update replaces a held one,
+  `fraction` is in `[0, 1)` and never goes back. The terminal success or failure message is the 100%.
+
+## Running a worker
+
+```bash
+export BROKER_URL=amqp://user:password@broker:5672/ IN_QUEUE_NAME=count-words_queue_in OUT_QUEUE_NAME=count-words_queue_out
+async-task-api-worker run my_module:worker      # or: python -m async_task_api_worker run my_module:worker
+```
+
+`my_module:worker` is a `Worker`, or a zero-argument factory function returning one; modules in the current directory can
+be imported. A definition error in the module exits with code 2 and one line. From code, `worker.run()` blocks until the
+process is stopped and `await worker.serve()` serves from an existing event loop.
+
+- The settings are read and validated first: an invalid configuration, or a task timeout that does not fit under the
+  broker's consumer timeout (`task timeout + WORKER_RETRY_BACKOFF_MAX_S + 60 s < WORKER_CONSUMER_TIMEOUT_S`), exits with
+  code 2 before any connection. Exit codes: 0 clean stop, 1 failure, 2 configuration or usage error.
+- A pydantic `ValidationError` raised by a startup hook (a settings class of your own, say) is a configuration error too:
+  one line naming the invalid fields, never their values (and `<Model> (a model-level check failed)` for a check that
+  belongs to no field), exit code 2. In job mode that fails the Job without a retry. So a startup hook must only validate
+  **configuration**: a hook that validates external data (a downloaded document, a response) must catch its own errors and
+  raise a `FatalError` or `RetryableError` from the task, where the task-level error model applies.
+- The queues are declared durable and with no arguments (the broker decides their type and policies), and consumed with
+  manual acknowledgements: a task is acked only after its result is published.
+- SIGTERM or SIGINT stops consuming, lets the in-flight tasks finish within `WORKER_SHUTDOWN_GRACE_S` (default 25 s),
+  requeues the ones that did not, closes the connection and exits 0. A second signal skips the rest of the grace period.
+  A `def` handler whose thread is still running after the drain, or an `async def` handler whose `asyncio.to_thread`
+  thread is (given 2 s after the drain), is logged and the process exits at once with code 1 (only for `run`, never for
+  `serve()`). The whole shutdown is bounded: the process exits at most
+  `max(WORKER_SHUTDOWN_GRACE_S, 5)` + 17 s after the signal (5 s for the nacks of the cancelled tasks, 5 s to close the
+  connection, and 5 s in total, `WORKER_SHUTDOWN_HOOKS_TIMEOUT_S`, for all the shutdown hooks together, each getting what is
+  left). Set a pod's `terminationGracePeriodSeconds` to at least that. A signal during startup does not wait for it: the
+  connection attempt and the startup hooks are cancelled and the process exits 0 (a hook that blocks the event loop
+  cannot be interrupted).
+- **Retries and crash-loop protection need quorum queues** (the broker's default queue type, as in the platform's
+  chart). A classic queue gives no delivery counter: there, a `RetryableError` gets one retry, then concludes with its
+  own code, and a warning says so.
+- Refused broker credentials exit with code 2 right away instead of being retried.
+- The attempt number of a delivery (`ctx.attempt`) counts every time the broker handed the message out. A
+  `RetryableError` requeues until attempt `WORKER_DELIVERY_LIMIT`, then concludes with its own code. A delivery past
+  that limit (a crash loop) is concluded with `TASK_ABANDONED_AFTER_REDELIVERIES` without running the handler.
+
+## Probes, metrics and logs
+
+A small HTTP server runs on `HEALTH_CHECK_HOST:HEALTH_CHECK_PORT` (default `0.0.0.0:8083`) in both modes, from the very
+start of the process until the end of the shutdown.
+
+| Path | Answer |
+|---|---|
+| `GET /health` | Liveness. 200 `{"status": "ok"}`, or 503 `TASK_OVERRUN` when a `def` handler is still running `WORKER_TASK_OVERRUN_GRACE_S` after its deadline. It consults no dependency. |
+| `GET /ready` | Readiness. 200 with a `components` map, or 503 `DEPENDENCIES_NOT_READY` (with the same `components` in `error`) when the broker is disconnected, the worker is draining, or one of the probes registered with `@worker.readiness_probe("name")` raises or exceeds `WORKER_PROBE_TIMEOUT_S` (3 s). Probes run in parallel. A `ProbeError` message is shown as the detail; any other exception only by its class name. |
+| `GET /metrics`, `GET /internal/metrics` | Prometheus text exposition. |
+| `GET /__version__` | `/app/version.json` of the image, or a `dev` document. |
+
+Errors use the platform's format, `{"status": "error", "error": {"code", "message"}}` (404 `NOT_FOUND`, 405
+`METHOD_NOT_ALLOWED`, 500 `PROBE_FAILED`). `broker` and `draining` are reserved component names. `/ready` is also 503 in
+job mode once the quota is reached and the consumer cancelled.
+
+The server is bounded: at most 32 connections are served at once (the others are closed at once), reading the request,
+writing the answer and closing each take at most 5 s, and concurrent `/ready` requests share a single evaluation of the
+probes.
+
+**Startup.** `/health` answers while the startup hooks run, but only as long as the event loop is free: a hook that loads a
+model or a large file synchronously blocks it, `/health` stops answering and the kubelet restarts the pod in a loop. Run
+heavy loading in `asyncio.to_thread`, or give the container a `startupProbe`.
+
+Metrics have no task, client or service label (the scrape adds the pod and service): `worker_tasks_total{status}`,
+`worker_task_duration_seconds`, `worker_messages_published_total{message_type}`, `event_loop_lag_seconds{component}`,
+`worker_task_failures_total{code}`, `worker_task_retries_total`, `worker_poison_messages_total{reason}`,
+`worker_publish_failures_total{message_type}`, `worker_ack_failures_total`, `worker_tasks_in_flight`,
+`worker_shutdown_requeued_total`, `worker_progress_dropped_total{reason}` and `worker_sdk_info`, plus the process, platform
+and GC collectors.
+
+Logs are one JSON object per line on stdout (`ts`, `level`, `logger`, `msg`, and `task_id`, `service`, `attempt` when
+bound; `ctx.logger` carries them, and so do the records of any library logging inside a handler, on the SDK's handler).
+`LOG_LEVEL` sets the level. If the application configured the root logger before running the worker, its handlers are
+kept and the SDK adds none (no line is printed twice): the format is then the application's, and so is the level of
+the `aio_pika.tools` logger, whose two ERROR lines on a dropped connection the SDK otherwise logs as warnings (the
+connection then reconnects by itself). To still get the task fields on your own handler, chain a record factory:
+
+```python
+import logging
+from async_task_api_worker.observability.logging import TaskContextFilter
+
+task_fields = TaskContextFilter()
+previous_factory = logging.getLogRecordFactory()
+
+
+def factory(*args, **kwargs):
+    record = previous_factory(*args, **kwargs)
+    task_fields.filter(record)
+    return record
+
+
+logging.setLogRecordFactory(factory)
+```
+
+Every delivery ends with exactly one INFO decision line, for instance `Delivery settled: outcome=failure action=conclude
+code=NOT_ALLOWED attempt=1/5`, with the fields `task_id`, `attempt`, `delivery_limit`, `outcome` (`success`, `failure`,
+`poison`, `retry`, `publish_failed`, `shutdown_requeued`, `cancelled`, `engine_error`), `action` (`ack`, `conclude`,
+`nack-requeue`) and `code`: `grep <task_id>`
+tells the whole story of a task. Payloads and secrets are never logged.
+
+## Deployment or Job
+
+The same worker code and image run as a long-lived consumer (a Kubernetes Deployment) or as a one-shot process (a
+Job, for instance one started per message by KEDA's `ScaledJob`). The deployment picks the mode with `WORKER_MODE`; the
+`Worker` definition does not change.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `WORKER_MODE` | `service` | `service` consumes until SIGTERM; `job` is one-shot. Any other value exits with code 2. |
+| `WORKER_JOB_MAX_TASKS` | `1` | Job mode: stop consuming at this many deliveries, finish them, and exit. |
+| `WORKER_JOB_IDLE_TIMEOUT_S` | `10` | Job mode: exit when no delivery is in hand and none arrives for this long (another pod probably took the message). |
+| `WORKER_JOB_CONNECT_TIMEOUT_S` | `30` | Job mode: give up and exit 1 when the broker stays unreachable for this long. Service mode retries forever. |
+
+In job mode the prefetch is forced to 1, whatever `WORKER_CONCURRENCY` says (it then only sizes the handler semaphore
+and the thread pool). The quota counts deliveries **on arrival**: any delivery counts, poison ones and redeliveries past
+the limit included, and consuming stops as soon as the last one is in hand. The exit code reports the **pod**, not the
+task: a task that succeeds, fails (`FatalError`, timeout, invalid input), or is requeued (`RetryableError`) all exit 0,
+and so does an idle exit, because a failed task is a business outcome already published to the client. Exit 1 (an
+infrastructure failure such as a broker unreachable for `WORKER_JOB_CONNECT_TIMEOUT_S`, or a `def` handler stuck after
+the drain) and 2 (invalid configuration) stay non-zero, so the Job's `backoffLimit` applies to them. SIGTERM and
+`activeDeadlineSeconds` drain exactly as in service mode.
+
+## S3 extra
+
+```bash
+pip install 'async-task-api-worker[s3]'
+```
+
+`async_task_api_worker.s3` reads and writes objects on an S3-compatible store (AWS, Scaleway, MinIO). The core package
+never imports it, and importing it without the extra raises an `ImportError` that names `[s3]`. Blocking boto3 calls run
+in a thread, so the event loop is never blocked.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `S3_BUCKET_NAME` | required | The bucket. |
+| `S3_ENDPOINT_URL` | AWS | The endpoint of a non-AWS store. |
+| `S3_REGION_NAME` | `fr-par` | The region the requests and the presigned URLs are signed for. Scaleway rejects the one boto falls back to (`us-east-1`), so the default is the deployments' region: set it for any other store. |
+| `S3_ACCESS_KEY`, `S3_SECRET_KEY` | boto's credential chain | Both or neither. Held as secrets: never printed or logged. |
+| `S3_VERIFY_SSL` | `true` | Verify the certificate of the endpoint. |
+| `S3_CONNECT_TIMEOUT_S`, `S3_READ_TIMEOUT_S` | `10`, `60` | botocore timeouts of one attempt (capped by the time left before `deadline`, see below). |
+| `S3_MAX_ATTEMPTS` | `3` | Attempts of botocore's standard retry mode (the initial one included): the only retry layer. Past it, a `RetryableError` hands the task back to the broker. |
+
+```python
+import time
+
+from async_task_api_worker import TaskContext, Worker
+from async_task_api_worker.s3 import ObjectStorage, S3Settings
+
+worker = Worker("summarize")
+storage = ObjectStorage(S3Settings())  # reads the S3_* variables
+
+
+@worker.readiness_probe("s3")
+async def s3_ready() -> None:
+    await storage.check_access()  # raises ProbeError: /ready answers 503 with this dependency down
+
+
+@worker.on_shutdown
+async def close_storage() -> None:
+    await storage.aclose()
+
+
+@worker.task(timeout=60.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    data = await storage.download(task_input.file_key, max_bytes=20_000_000, deadline=ctx.deadline)
+    ...
+    await storage.upload("results/42.json", payload, content_type="application/json", deadline=ctx.deadline)
+    return Output(download_url=await storage.presign_get("results/42.json", expires_in=3600))
+```
+
+- `head_size(key, *, deadline)`, `download(key, *, max_bytes, deadline)`, `download_to(key, path, *, max_bytes, deadline)`
+  (streams to a file, which a failure removes), `upload(key, data, *, content_type=None, deadline)`,
+  `presign_get(key, *, expires_in)` (1 second to 7 days, no request), `check_access()`, `aclose()`; the storage is also an
+  async context manager. `content_type` is stored as given; without it the store applies its default.
+- `deadline` is `ctx.deadline`. A call that starts past it, or still runs when it passes, raises
+  `RetryableError(UPSTREAM_UNAVAILABLE)`. The botocore timeouts of a call are capped by the time left (rounded up to 1,
+  2, 5, 10, 30 or 60 s: a client is built per value), so a call abandoned at its deadline ends soon after it.
+- A blocking boto3 call cannot be interrupted. It runs in a **daemon thread the SDK owns**, not in the event loop's
+  default executor: an abandoned call (past its deadline, or when the worker stops) is left behind, its result
+  discarded, and never delays the exit nor turns a clean exit (code 0, a Job's included) into exit 1. Worst case, it
+  holds one thread and one connection for the botocore bound of its call: at most `S3_MAX_ATTEMPTS` times the capped
+  connect and read timeouts, and at most 3 times 70 s (about 3.5 minutes) for a call with more than a minute left.
+  An upload abandoned at its deadline can still complete in the background after the task was requeued: write outputs to
+  idempotent or per-attempt keys.
+  `check_access()` answers within 3 s whatever the settings (`ObjectStorage(probe_budget_s=...)`), and its thread
+  lingers the same way.
+- The size is checked three times: on the HEAD, before any byte is read; on the GET, since the object may have been
+  replaced in between; and on the bytes actually read. Over `max_bytes` is `FatalError(FILE_TOO_LARGE)`, and memory
+  never holds more than `max_bytes` plus one byte.
+- Errors: a missing key is `FatalError(DOCUMENT_NOT_FOUND)`. Connection errors, timeouts, 5xx, 408 and 429, and the
+  codes `RequestTimeout`, `SlowDown`, `InternalError`, `ServiceUnavailable`, `Throttling` whatever the status, are
+  `RetryableError(UPSTREAM_UNAVAILABLE)`. Anything else (`AccessDenied`, `NoSuchBucket`, no credentials) is an
+  `ObjectStorageError` carrying the operation and the S3 code, which the runtime reports as `INTERNAL_ERROR`. No error
+  text contains the endpoint, a key or a credential, and the botocore exception is not chained to it.
+- **AWS answers 403, not 404, to a HEAD on a missing key when the credentials lack `s3:ListBucket`.** That is
+  indistinguishable from a real permission error and ends as an `ObjectStorageError`: grant `s3:ListBucket` to get
+  `DOCUMENT_NOT_FOUND`. `check_access()` sends a HEAD on the bucket, so it needs that permission too.
+- A presigned URL embeds the endpoint and the key: give it to the client, do not log it.
+
+## LLM extra
+
+```bash
+pip install 'async-task-api-worker[llm]'
+```
+
+`async_task_api_worker.llm` is a chat client for OpenAI-compatible servers (vLLM, OpenAI, Scaleway...) over `httpx`.
+There is no `openai` package behind it, so no hidden retry layer. Importing it without the extra raises an
+`ImportError` that names `[llm]`.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `LLM_BASE_URL` | required | The API root, for instance `http://vllm:8000/v1`. |
+| `LLM_API_KEY` | none | Sent as a bearer token. Held as a secret. A deployment maps its own secret onto this name at the environment level, for instance with a Kubernetes `secretKeyRef`. |
+| `LLM_VERIFY_SSL` | `true` | `false` turns off the certificate check (a hub with a private CA). |
+| `LLM_CONNECT_TIMEOUT_S` | `10` | Connection timeout, capped by the time left before the task deadline. |
+| `LLM_TIMEOUT_S` | `120` | Timeout of each operation of a request (read, write), capped by the time left. The whole request is also cut at the task deadline. |
+| `LLM_RETRY_ATTEMPTS` | `3` | Requests in total (the first one included). |
+| `LLM_RETRY_AFTER_MAX_S` | `60` | Cap of the wait asked for by `Retry-After` or `retry-after-ms`. |
+| `LLM_RETRY_BACKOFF_BASE_S`, `LLM_RETRY_BACKOFF_MAX_S` | `1`, `30` | Without `Retry-After`: full jitter below `base * 2^(attempt-1)`, at most `max`. |
+
+```python
+from async_task_api_worker import TaskContext, Worker
+from async_task_api_worker.llm import ChatMessage, ImageUrlPart, LLMClient, LLMSettings, Role, TextPart
+
+worker = Worker("describe-page")
+llm = LLMClient(LLMSettings())  # reads the LLM_* variables
+
+
+@worker.on_shutdown
+async def close_llm() -> None:
+    await llm.aclose()
+
+
+@worker.task(timeout=120.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    page = ImageUrlPart.from_bytes(task_input.png, media_type="image/png")
+    result = await llm.chat(
+        [ChatMessage(Role.USER, [TextPart("Transcribe this page."), page])],
+        model="my-vision-model",
+        deadline=ctx.deadline,
+        max_tokens=4096,
+        temperature=0.0,
+        extra_body={"skip_special_tokens": False},  # vLLM-specific fields, merged at the top level
+    )
+    return Output(text=result.text)
+```
+
+- `chat(messages, *, model, deadline, max_tokens=None, temperature=None, response_format=None, extra_body=None)`
+  returns a `ChatResult(text, finish_reason, model, usage)`. A message is plain text or a list of `TextPart` and
+  `ImageUrlPart` (a `data:image/...` URL or an `https://` one: anything else is a `ValueError`).
+  `response_format` and `extra_body` are JSON objects; an `extra_body` key that would replace `model`, `messages`,
+  `stream` or a field set by an argument is a `ValueError`.
+- Retries happen on 408, 429, 500, 502, 503, 504 and on any `httpx` error (connection errors, timeouts, an undecodable body). `Retry-After` (seconds or HTTP date)
+  and `retry-after-ms` set the wait. The client never sleeps past `deadline` and never sends a request after it: when
+  the wait does not fit in the time left it gives up at once.
+- Giving up on a transient failure (attempts used up, or no time left) is `RetryableError(UPSTREAM_UNAVAILABLE)`, and so
+  is any other 5xx, without in-process retry, except 501 and 505 (a server that does not implement the route or the protocol: a deployment problem). Other statuses are `FatalError(LLM_REQUEST_REJECTED)`; an answer that is not
+  JSON, has no choice or no text is `LLM_OUTPUT_INVALID`; `finish_reason` `length` is `LLM_OUTPUT_TRUNCATED` and
+  `content_filter` is `LLM_OUTPUT_FILTERED`. No error text contains the URL, a header or a response body.
+- Use `async with LLMClient(settings) as llm:` or call `aclose()`.
+- `embed()` is not provided yet.
+- `LLMClient` also takes `transport=` (an `httpx` transport) and `clock`, `sleep`, `jitter` and `now` (time and
+  randomness). They are **test seams, outside the stability guarantee**: they may change or go with a minor release.
+  `ObjectStorage`'s `client`, `clock` and `probe_budget_s` are test seams too.
+- `httpx` logs every request URL at INFO. `configure_logging` keeps the `httpx` and `httpcore` loggers at WARNING when
+  the SDK installs its own log handler. An application that installs its own handler before running the worker still
+  gets those INFO lines (URLs included) unless it raises these two loggers itself.
+
+## Testing your worker
+
+`async_task_api_worker.testing` runs your task in memory through the real engine (decoding, time limit, retries, error
+mapping, acknowledgements), with no broker and no Docker:
+
+```python
+from pydantic import BaseModel
+
+from async_task_api_worker import FatalError, TaskContext, Worker
+from async_task_api_worker.testing import Outcome, ProgressRecorder, WorkerHarness, make_task_context
+
+
+class Input(BaseModel):
+    text: str
+
+
+class Output(BaseModel):
+    words: int
+
+
+worker = Worker("count-words")
+
+
+@worker.task(timeout=30.0)
+async def handle(task_input: Input, ctx: TaskContext) -> Output:
+    if not task_input.text.strip():
+        raise FatalError("EMPTY_TEXT", "There is nothing to count.")
+    await ctx.progress(0.5)
+    return Output(words=len(task_input.text.split()))
+
+
+async def test_counts_the_words() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "hello big world"})
+
+    run.assert_succeeded()
+    assert run.response == {"words": 3}
+    assert run.message_types == ("started", "progress", "success")
+
+
+async def test_an_empty_text_fails_with_its_code() -> None:
+    async with WorkerHarness(worker) as harness:
+        run = await harness.submit({"text": "  "})
+
+    run.assert_failed(code="EMPTY_TEXT")
+    assert run.outcome is Outcome.ACKED
+
+
+async def test_the_handler_alone_with_a_context_you_build() -> None:
+    recorder = ProgressRecorder()
+    ctx = make_task_context(recorder=recorder)
+
+    assert await handle(Input(text="a b"), ctx) == Output(words=2)
+    assert [update.fraction for update in recorder.updates] == [0.5]
+```
+
+- `harness.submit(body, client_id=..., input_refs=..., delivery_count=...)` builds the envelope the API publishes;
+  `submit_raw(bytes)` sends bytes as they are (a poison message). The result is a `TaskRun`: `messages` (decoded) and
+  `raw` (the published bytes), `message_types` (all three are tuples), `outcome` (`ACKED`, `NACKED_REQUEUE`), `response`,
+  `error`, and the two assertions. `task_id` is the envelope's, or `None` for bytes that do not carry one.
+- `delivery_count` is the broker's `x-delivery-count`: pass `0`, then `delivery_count=n` to see a `RetryableError`
+  requeue until the last attempt (`worker_delivery_limit`), which concludes with the error's own code. Retry backoffs are
+  a millisecond; every other setting is the production default (progress throttling included).
+- `settings_overrides={"worker_task_timeout_s": 0.1, ...}` takes `WorkerSettings` field names; no environment variable is
+  read, and the time budget is checked as at startup. `harness.fail_next_publish("success")` makes the next publish (of
+  that message type, or of any) fail once, to test the requeue. Use `async with` (or `await harness.aclose()`).
+- `make_task_context` and `make_sync_task_context` build the context of an `async def` and of a `def` handler, to call
+  the handler directly; `ProgressRecorder` collects what it reports.
+
+## Conformance
+
+The conformance suite checks, in memory, that a worker honours the platform contract with the SDK runtime under it.
+It needs no broker and no Docker, so it runs in your own CI.
+
+```bash
+pip install 'async-task-api-worker[testing]'   # the [testing] extra only adds pytest, for the plugin
+async-task-api-worker conformance my_package.worker:worker --cases conformance.json --junit conformance.xml
+pytest -p async_task_api_worker.testing.pytest_plugin --async-task-api-worker my_package.worker:worker \
+  --async-task-api-worker-cases conformance.json
+```
+
+The command exits **0** when every check ran and none failed, **1** with a readable report when one failed, **2** when
+the target or a file (cases, contract) cannot be read, and **3** when nothing failed but a check was skipped for lack
+of input (see below): a green run must not prove less than it claims. The opt-in C11 is the only benign skip.
+
+The pytest plugin adds one test per check (a check that cannot run is a skipped test with its reason). The
+plugin is not loaded by default: name it with `-p`, or put `pytest_plugins = ["async_task_api_worker.testing.pytest_plugin"]`
+in your `conftest.py`. `async_task_api_worker.testing.reference:worker` is the SDK's own reference worker: the suite
+always passes on it, with the cases it ships: `--cases "$(python -c 'from async_task_api_worker.testing.reference import CASES_FILE; print(CASES_FILE)')"`
+(body `{"sleep_s": 0, "fail_with": null, "retryable": false}`).
+
+`conformance.json` (or `--async-task-api-worker-cases` for pytest) lists the cases of your service:
+
+```json
+[
+  {"name": "counts words", "body": {"text": "hello world"}, "expect": "success"},
+  {"name": "rejects empty text", "body": {"text": ""}, "expect": {"failure": "INPUT_INVALID"}}
+]
+```
+
+| Check | Exercises | What it proves |
+|---|---|---|
+| C01 | worker | Needs cases: skipped without them (the handler's own behaviour is not checked). Each case: `started`, then exactly one terminal message, then the ack; the outcome is the expected one. A delivery that is not settled exactly once fails here. |
+| C02 | worker | Every published message is a valid protocol message, byte-encoded canonically, with a zone-aware timestamp. |
+| C03 | worker | An invalid input (built from your input model: a missing field, a wrong type, an unknown field) fails with `INPUT_INVALID` and never reaches the handler. Skipped when the model accepts everything tried. |
+| C04 | sdk | Every kind of poison message is acked and produces no message. |
+| C05 | sdk | An unexpected exception becomes `INTERNAL_ERROR`, and its text never reaches a published message. |
+| C06 | sdk | On an emulated quorum queue, a `RetryableError` is requeued until `WORKER_DELIVERY_LIMIT`, then concluded with its own code: one ack, nothing dead-lettered. |
+| C07 | sdk | A terminal (or `started`) message that fails to publish requeues the delivery, and never acks it. |
+| C08 | sdk | A task past its time limit fails with `TASK_TIMEOUT` and is acked. |
+| C09 | sdk | A drain lets an in-flight task finish and ack, requeues one that outlives the grace period, and consumes nothing after the stop. |
+| C10 | sdk | A burst of progress updates is throttled, stays in `[0, 1)` and never goes back, and nothing follows the terminal message. |
+| C11 | worker | **Opt-in** (`--contract contrat.json`): the file `{"nom": <service>, "entree": <JSON schema>}` matches the service name and the input model's schema. |
+| C12 | sdk | `/health` and `/metrics` answer, and `/ready` is 200 while consuming and 503 once the broker is gone. |
+
+**`worker` checks exercise your own code** (C01 to C03, and C11 on your model); **`sdk` checks verify the guarantees of the
+SDK runtime** under your models and settings (retry, drain, probes...): C05 to C10 and C12 run them with a handler of
+their own (a failure, a sleeper) in place of yours, so they cannot fail because of your handler. A worker whose handler
+fails on every input passes them, and fails C01 as soon as you give it a `success` case. Every check but C03 and C11
+needs an input your model accepts: the first `success` case, else one built from the schema. Without one
+they are skipped, the report lists them above its summary ("Not checked, for lack of input") and the exit code is 3. Your
+startup hooks, shutdown hooks and readiness probes are not run by default (they need the real dependencies), so a worker
+whose own probe always fails still passes C12, which proves the SDK's `/ready` semantics: pass `--with-probes`
+(`--async-task-api-worker-with-probes`, `with_probes=True`) to run them in C12 when their dependencies are reachable. The
+settings are the production defaults, not your environment (`settings_overrides` of `ConformanceSuite` applies yours).
+
+The contract file of C11 is `{"nom": <service>, "entree": <JSON schema>}`: the keys are those of the existing `contrat.json`
+manifest, kept so that those files work as they are. A malformed one is an error of usage (exit 2), not a failed check.
+
+The pieces are public, for your own tests:
+
+- `InMemoryBroker(delivery_limit=5, prefetch=1)` emulates the quorum queue with the counters measured on RabbitMQ 4.3 and
+  later (ADR 0005): a voluntary `nack(requeue=True)` only increments `x-acquired-count` and never dead-letters, a delivery
+  returned after a failure (`disconnect()`) increments both counters and is dead-lettered after `delivery_limit + 1`
+  deliveries. It is a transport: `submit(bytes)`, `published`, `published_types()`, `dead_lettered`, `ready`, `unacked`,
+  `fail_next_publish()`, `disconnect()` / `reconnect()`, `wait_idle()`, `acks` and `nacks` (the `requeue` flags, in order). The suite runs the real process lifecycle on it.
+- `FakeApi().submission(body, client_id=..., input_refs=...)` builds the envelope the API publishes, byte for byte;
+  `FakeListener` validates what a worker publishes against the protocol models and applies the listener's rules (a
+  terminal task is never overwritten; a progress of 1 or more is ignored and the task stays in progress, as the real listener does, although the models refuse it): `register(task_id)`, `ingest(raw)`,
+  `status(task_id)`.
+- `ConformanceSuite(worker, cases, contract=None, settings_overrides=None).run()` returns a `ConformanceReport`
+  (`passed`, `complete`, `results`, `to_text()`, `to_junit_xml()`); `run_check("C06")` runs one check. The text and JUnit
+  reports give each check's kind. The keyword arguments of `ConformanceSuite` that start with an underscore are test seams
+  of the suite's own tests, outside the stability guarantee.
+
+## Manifest and protocol document
+
+```bash
+async-task-api-worker manifest my_module:worker --title "Count words" --description "Counts the words of a text." \
+    --class court --output contrat.json          # the manifest of the service (the input schema is derived)
+async-task-api-worker manifest my_module:worker --check contrat.json   # exit 1 when the file drifted from the model
+async-task-api-worker spec                      # the AsyncAPI 3.0 document of the protocol, from the SDK models
+async-task-api-worker spec --check asyncapi.json   # exit 1 when a committed copy is out of date
+```
+
+- The manifest uses the keys of the platform's `contrat.json` format (`nom`, `titre`, `description`, `classe`, `entree`,
+  and the optional `description_courte`, `icone`, `taille_max_fichier_mio`, `gpu`). `nom` is the service name and `entree` is
+  `input_model.model_json_schema()`: it can never be written wrong by hand, and `--check` proves a committed file is
+  still right. `--class` is one of `immediat`, `court`, `long`; the catalogue reads it, so give it when the file feeds
+  the catalogue. `build_manifest`, `parse_manifest`, `load_manifest` and `check_manifest` are in
+  `async_task_api_worker.manifest`.
+- The file is what the conformance check C11 reads (`conformance --contract contrat.json`): both sides use the same keys, so the manifest you generate is the contract file you check.
+- Set `WORKER_MANIFEST_PATH` to a manifest in the image to make the worker refuse to start (exit 2, before any
+  connection) when it does not read, names another service or no longer matches the input model.
+- Exit codes of the commands: 0 ok, 1 a `--check` found a drift, 2 usage or an unreadable file.
+- The protocol document is also published in the repository, under `docs/protocol/`, with the versioning rules, the
+  error codes and the acknowledgement semantics.
+
+## Development
+
+From this directory:
+
+```bash
+uv sync --locked --all-extras
+uv run ruff check . && uv run ruff format --check .
+uv run ty check src
+uv run pytest -m "not integration" -q --cov=async_task_api_worker --cov-branch --cov-fail-under=95
+```
+
+The integration tests need Docker (they start RabbitMQ with the platform's policy through testcontainers):
+
+```bash
+uv run pytest -m integration -q
+```
+
+Add dependencies with `uv add` from this directory, never by editing `pyproject.toml`.