Metadata-Version: 2.4
Name: nexus-queue
Version: 0.1.4
Summary: Nexus-Queue — portable taskiq + Redis Streams worker runtime: namespaced streams, versioned envelope, ports-and-adapters, retry/DLQ/idempotency/tracing/metrics middleware.
Project-URL: Homepage, https://github.com/Zetesis-Labs/PayloadAgents
Project-URL: Repository, https://github.com/Zetesis-Labs/PayloadAgents
Project-URL: Issues, https://github.com/Zetesis-Labs/PayloadAgents/issues
Author: Zetesis Labs
License: MIT
Keywords: dlq,ports-and-adapters,queue,redis,taskiq,worker
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: opentelemetry-api>=1.35
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35
Requires-Dist: opentelemetry-sdk>=1.35
Requires-Dist: prometheus-client>=0.20
Requires-Dist: pydantic>=2.9
Requires-Dist: redis>=5.0
Requires-Dist: structlog>=24.1
Requires-Dist: taskiq-redis>=1.1.1
Requires-Dist: taskiq>=0.11.18
Requires-Dist: uvicorn[standard]>=0.34
Description-Content-Type: text/markdown

# nexus-queue

Portable worker runtime for the **Nexus-Queue** standard: taskiq + Redis Streams,
domain-agnostic, ports-and-adapters. One project builds queues the same way as
the next, and a worker's handlers move between projects unchanged.

What this package owns (the parts that are the *same* across projects):

- **Namespaced streams** — `nq:{project}:{queue}` (+ `:cg`, `:dlq`) and
  `nq:{project}:status`, so multiple projects/queues coexist on one Redis
  (the default global `"taskiq"` stream is never used).
- **Versioned envelope** — standard labels (`nq_v`, `nq_task`, `nq_tenant`,
  `nq_idem`, `nq_trace`, `nq_enqueued_at`, `nq_priority`) on top of taskiq's
  message, plus typed pydantic payloads.
- **Ports** — `JobStatePort`, `BlobStorePort`, `IndexPort`, `StatusEventPort`.
  Handlers depend only on these; each project supplies the adapters
  (e.g. Payload vs Postgres/MinIO).
- **Middleware stack** (broker-level): idempotency (dedup on `nq_idem`),
  DLQ (dead-letter on retry-exhaustion instead of silent drop), retries with
  exponential backoff + jitter, OTel tracing (`nq_trace` propagation), and
  Prometheus metrics.
- **Producer + kicker** — a Python `Publisher` and a generic HTTP kicker for
  non-Python producers. The TypeScript producer client ships as
  `@zetesis/nexus-queue`.

Spec: `nexus-queue-spec.md`.

Released via release-please on every conventional commit to `main`
(scope `nexus-queue`).
