Rewrite README in pageres style with API docs and promo banner

Author: false200

README.md

@@ -1,39 +1,32 @@
-# queuebridge
+# ![queuebridge](media/promo.svg)
 
-**Pass Pydantic models to `.delay()` / `.send()` / `enqueue_job()` — get models back from results.**
+[![PyPI version](https://img.shields.io/pypi/v/queuebridge.svg)](https://pypi.org/project/queuebridge/)
+[![Python](https://img.shields.io/pypi/pyversions/queuebridge.svg)](https://pypi.org/project/queuebridge/)
+[![CI](https://github.com/false200/queuebridge/actions/workflows/ci.yml/badge.svg)](https://github.com/false200/queuebridge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Bidirectional Pydantic typing for [Celery](https://docs.celeryq.dev/), [Dramatiq](https://dramatiq.io/), and [Arq](https://arq-docs.helpmanual.io/) with one shared wire codec.
+Bidirectional [Pydantic](https://docs.pydantic.dev/) serialization for [Celery](https://docs.celeryq.dev/), [Dramatiq](https://dramatiq.io/), and [Arq](https://arq-docs.helpmanual.io/). One shared wire codec — pass models on enqueue, get models back from results.
 
-## The problem
+Celery 5.5+ `pydantic=True` only validates on the worker. Callers still `model_dump()` before `.delay()`, and `.get()` returns a `dict`. Dramatiq chokes on models and UUIDs. Arq defaults to pickle. **queuebridge** fixes all three with a thin codec + backend adapters.
 
-Celery 5.5+ added `pydantic=True`, but it only validates on the **worker**:
-
-- Callers must still `model_dump()` before `.delay()` — passing a model raises `TypeError: Object of type X is not JSON serializable` ([celery#9442](https://github.com/celery/celery/issues/9442))
-- `.get()` returns a `dict`, not your model
-
-Dramatiq's default JSON encoder fails on models, UUIDs, and datetimes ([dramatiq#660](https://github.com/Bogdanp/dramatiq/issues/660)).
-
-Arq defaults to pickle with no Pydantic story ([arq#497](https://github.com/python-arq/arq/issues/497)).
+## Install
 
-```
-Producer                    Worker                      Client
-────────                    ──────                      ──────
-.delay(model)  ──X──>      pydantic=True validates     .get() → dict
-(model_dump() required)     args on worker only
+```sh
+pip install queuebridge
 ```
 
-**queuebridge** fixes the producer side and client-side result decoding with a shared `__qb__` tagged wire format.
-
-## Install
+Extras:
 
-```bash
+```sh
 pip install queuebridge[celery]     # Celery + Kombu
 pip install queuebridge[dramatiq]   # Dramatiq
 pip install queuebridge[arq]        # Arq + msgpack
-pip install queuebridge[all]        # everything
+pip install queuebridge[all]        # all backends
 ```
 
-## Quickstart
+Requires **Python 3.10+** and **Pydantic v2**.
+
+## Usage
 
 ### Celery
 
@@ -49,15 +42,10 @@ register_queuebridge(app)
 def process_order(order: OrderCreate) -> OrderResult:
     return OrderResult(id=order.id, status="processed")
 
-# Enqueue with a model directly
 ar = process_order.delay(OrderCreate(id=1, sku="ABC"))
-
-# Get a model back (not a dict)
 result = typed_result(ar, OrderResult).get(timeout=10)
 ```
 
-> **Note:** Celery cannot safely monkey-patch `AsyncResult.get()` globally. Use `typed_result()` for typed client results.
-
 ### Dramatiq
 
 ```python
@@ -98,9 +86,162 @@ class WorkerSettings:
     job_deserializer = deserialize
 ```
 
+## API
+
+### `encode(value, *, tag_models=True)`
+
+Recursively transform a Python value into a JSON-serializable structure.
+
+#### value
+
+*Required*  
+Type: `Any`
+
+The value to encode — Pydantic models, nested containers, `UUID`, `datetime`, `Decimal`, `Enum`, etc.
+
+#### tag_models
+
+Type: `boolean`  
+Default: `true`
+
+When `true`, `BaseModel` instances are wrapped in a `__qb__` envelope with a fully-qualified type name. When `false`, models are dumped with `model_dump(mode="json")` only.
+
+```python
+from queuebridge import encode, decode
+from myapp.models import OrderCreate
+
+wire = encode(OrderCreate(id=1, sku="ABC"))
+restored = decode(wire, OrderCreate)
+```
+
+---
+
+### `decode(value, hint=Any, *, strict=False)`
+
+Recursively decode a wire value back to Python using an optional type hint.
+
+#### value
+
+*Required*  
+Type: `Any`
+
+Wire value — primitives, lists, dicts, or `__qb__` envelopes.
+
+#### hint
+
+Type: `Any`  
+Default: `Any`
+
+Type hint used for validation. `TypeAdapter(hint).validate_python()` is used when the hint is concrete.
+
+#### strict
+
+Type: `boolean`  
+Default: `false`
+
+When `true`, raise `QueuebridgeDecodeError` if the value cannot be decoded.
+
+---
+
+### `decode_wire(value)`
+
+Recursively unwrap `__qb__` envelopes without type hints. Used internally by Dramatiq's decoder.
+
+Type: `Any` → `Any`
+
+---
+
+### `register_queuebridge(app, *, strict=False)` — Celery
+
+Register the `queuebridge-json` Kombu serializer on a Celery app. Idempotent — safe to call twice.
+
+#### app
+
+*Required*  
+Type: `celery.Celery`
+
+#### strict
+
+Type: `boolean`  
+Default: `false`
+
+Reserved for future strict decode behavior.
+
+Sets `task_serializer`, `result_serializer`, and `accept_content` on the app.
+
+---
+
+### `typed_result(async_result, return_type)` — Celery
+
+Wrap a Celery `AsyncResult` so `.get()` returns a Pydantic model instead of a `dict`.
+
+#### async_result
+
+*Required*  
+Type: `celery.result.AsyncResult`
+
+#### return_type
+
+*Required*  
+Type: `type[T]`
+
+Returns `TypedAsyncResult[T]` — proxies `.id`, `.state`, `.ready()`, etc.
+
+> Celery cannot safely monkey-patch `AsyncResult.get()` globally. Use `typed_result()` on the client.
+
+---
+
+### `register_queuebridge(broker=None)` — Dramatiq
+
+Install `QueuebridgeEncoder` via `dramatiq.set_encoder()`. Call once at process startup.
+
+#### broker
+
+Type: `dramatiq.Broker | None`  
+Default: `None`
+
+If provided, also calls `dramatiq.set_broker(broker)`.
+
+---
+
+### `get_serializer_pair()` — Arq
+
+Returns `(serialize, deserialize)` callables for `job_serializer` / `job_deserializer`.
+
+```python
+serialize, deserialize = get_serializer_pair()
+```
+
+Uses **msgpack** over queuebridge-encoded dicts. Set on both `WorkerSettings` and `create_pool()`.
+
+---
+
+### `qb_task(fn)` — Arq
+
+Decorator that decodes wire args/kwargs using function type hints before your async task runs.
+
+Apply **outside** `@validate_call`:
+
+```python
+@qb_task
+@validate_call
+async def process_order(ctx, order: OrderCreate) -> OrderResult:
+    ...
+```
+
+---
+
+### `typed_result(job, return_type)` — Arq
+
+```python
+result = await typed_result(job, OrderResult)
+```
+
+Decode the `job.result()` payload into a Pydantic model.
+
 ## Wire format
 
-Non-JSON-native values are wrapped in a tagged envelope:
+Non-JSON-native values use a tagged envelope:
 
 ```json
 {
@@ -112,26 +253,58 @@ Non-JSON-native values are wrapped in a tagged envelope:
 }
 ```
 
-Decode uses function type hints (`TypeAdapter`) when tags are absent — a plain dict + `OrderCreate` hint still validates.
+| Python type | Encode | Decode |
+|-------------|--------|--------|
+| `BaseModel` | envelope + `model_dump(mode="json")` | `model_validate` or FQN import |
+| `UUID`, `datetime`, `Decimal`, `Enum` | tagged envelope | builtin dispatch |
+| `list`, `dict`, `set`, `tuple` | recurse | recurse via hint |
+| Primitives | pass through | pass through |
 
-## Security
+A plain `dict` + `OrderCreate` hint still validates — tags are for ambiguity, not required when hints are known.
+
+## Why not Celery `pydantic=True` alone?
 
-Deserialization resolves types by fully-qualified name (`import_fqn`). **Only deserialize from brokers you trust.** Module allowlisting is planned for v0.2.
+```
+Producer                    Worker                      Client
+────────                    ──────                      ──────
+.delay(model)  ──X──>      pydantic=True validates     .get() → dict
+(model_dump() required)     args on worker only
+```
+
+- [celery#9442](https://github.com/celery/celery/issues/9442) — models not JSON-serializable on enqueue
+- [dramatiq#660](https://github.com/Bogdanp/dramatiq/issues/660) — no Pydantic support
+- [arq#497](https://github.com/python-arq/arq/issues/497) — pickle default, Pydantic requested
 
 ## Comparison
 
-| Solution | Celery | Dramatiq | Arq | Bidirectional `.get()` |
-|----------|--------|----------|-----|------------------------|
+| Solution | Celery | Dramatiq | Arq | Typed `.get()` |
+|----------|--------|----------|-----|----------------|
 | Celery `pydantic=True` | worker only | — | — | no |
 | Blog / msgpack hacks | partial | partial | partial | varies |
-| **queuebridge** | yes | yes | yes | yes (`typed_result`) |
+| **queuebridge** | yes | yes | yes | yes |
+
+## Security
+
+Deserialization resolves types by fully-qualified name (`import_fqn`). **Only deserialize from brokers you trust.**
+
+`ALLOWED_MODULE_PREFIXES` allowlisting is planned for v0.2.
+
+## Examples
+
+| Path | Description |
+|------|-------------|
+| [`examples/celery_fastapi/`](examples/celery_fastapi/) | FastAPI enqueue + typed result polling |
+| [`examples/dramatiq_example/`](examples/dramatiq_example/) | Dramatiq + `validate_call` |
+| [`examples/arq_example/`](examples/arq_example/) | Arq worker with custom serializers |
+| [`examples/smoke_test_complex.py`](examples/smoke_test_complex.py) | End-to-end smoke test (no Redis) |
+| [`pypi_verify/run_complex.py`](pypi_verify/run_complex.py) | PyPI install verification script |
 
-## Roadmap
+## Related
 
-- `allowed_modules` security filter on `register_queuebridge()`
-- Optional pickle extra
-- Chord / chain signature support
+- [Celery Pydantic docs](https://docs.celeryq.dev/en/stable/userguide/tasks.html#argument-validation-with-pydantic) — worker-only validation
+- [Arq custom serializers](https://arq-docs.helpmanual.io/#custom-job-serializers) — msgpack hook point
+- [Dramatiq encoders](https://dramatiq.io/advanced.html#custom-encoders) — `set_encoder()` extension point
 
 ## License
 
-MIT
+MIT © [false200](https://github.com/false200)