unique_toolkit 2026.48.0.dev19__py3-none-any.whl → 2026.48.0.dev20__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,7 +19,9 @@ the interface may change.
19
19
  uv add 'unique-toolkit[activity-records]'
20
20
  ```
21
21
 
22
- The extra installs asyncpg and prometheus_client. Also install `opentelemetry-api`
22
+ The extra installs asyncpg and prometheus_client. `AmqpPublisher` needs the
23
+ `activity-records-amqp` extra on top (`uv add 'unique-toolkit[activity-records-amqp]'`),
24
+ which adds aio-pika. Also install `opentelemetry-api`
23
25
  (or the `otel` extra) so events get their correlationId from the active trace.
24
26
 
25
27
  ## Migration
@@ -59,7 +61,22 @@ used for both, so it must not share a cache that other callers keep warm.
59
61
  Delivery is done by a sender the caller supplies (`PublisherLike`):
60
62
  `async publish(events: list[dict]) -> None`. Raise a `TimeoutError` subclass on
61
63
  timeout. Any other exception means rejected and the row backs off. The caller
62
- owns the sender's connection. The GraphQL sender lands with UN-29210.
64
+ owns the sender's connection. `publishers.amqp_publisher.AmqpPublisher` (RabbitMQ) is the
65
+ production sender until UN-29210 lands the GraphQL one. It reads `AMQP_URL`, or
66
+ `AMQP_HOST` with `AMQP_USERNAME` and `AMQP_PASSWORD` (plus optional `AMQP_PORT`,
67
+ `AMQP_VHOST`, `AMQP_HEARTBEAT_INTERVAL_IN_SECONDS`), and fails at `connect()` if none is
68
+ set. Call `connect()` before `start()` and `close()` after `stop()`.
69
+ `publishers.logging_publisher.LoggingPublisher` only logs events and deletes the rows
70
+ without delivering them: local testing, never production.
71
+
72
+ `AmqpPublisher` declares the ingest queue and its dead letter queue before the first
73
+ publish, with the same arguments as the Node producer and consumer (durable; the ingest
74
+ queue dead letters to the default exchange with the DLQ name as routing key). If a queue
75
+ already exists with other arguments, RabbitMQ refuses and `publish` raises
76
+ `ChannelPreconditionFailed`; the relay then keeps backing off every row until the queue
77
+ is fixed. The queues are not bound to a custom `exchange`, so that case still needs its
78
+ own bindings. A wrong broker host or password shows up as publish timeouts, not as a
79
+ startup error.
63
80
 
64
81
  ## FastAPI
65
82
  Create one runtime and start and stop it in the FastAPI lifespan:
@@ -1,10 +1,11 @@
1
- """Activity Records settings: size limits."""
1
+ """Activity Records settings: size limits and the broker connection."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
5
  from typing import Final, Self
6
+ from urllib.parse import quote
6
7
 
7
- from pydantic import Field, model_validator
8
+ from pydantic import Field, SecretStr, model_validator
8
9
  from pydantic_settings import BaseSettings, SettingsConfigDict
9
10
 
10
11
  from unique_toolkit.experimental.resources.activity_records.json_size import (
@@ -94,3 +95,46 @@ class ActivityRecordsConfig(BaseSettings):
94
95
  "maximally-sized event always fits a batch by itself"
95
96
  )
96
97
  return self
98
+
99
+
100
+ class AmqpSettings(BaseSettings):
101
+ """``AMQP_URL`` when set; otherwise ``AMQP_HOST``, ``AMQP_USERNAME`` and ``AMQP_PASSWORD``
102
+ (all required) with optional port and vhost."""
103
+
104
+ model_config = SettingsConfigDict(
105
+ env_prefix="AMQP_", extra="ignore", hide_input_in_errors=True
106
+ )
107
+
108
+ url: SecretStr | None = None
109
+ host: str | None = None
110
+ port: int = 5672
111
+ username: str = ""
112
+ password: SecretStr = Field(default_factory=lambda: SecretStr(""))
113
+ vhost: str = "/"
114
+ heartbeat_interval_in_seconds: int = 30
115
+
116
+ @model_validator(mode="after")
117
+ def _require_a_broker(self) -> Self:
118
+ if self._configured_url():
119
+ return self
120
+ if not (self.host and self.username and self.password.get_secret_value()):
121
+ raise ValueError(
122
+ "AMQP_URL, or AMQP_HOST with AMQP_USERNAME and AMQP_PASSWORD, is required"
123
+ )
124
+ return self
125
+
126
+ def _configured_url(self) -> str | None:
127
+ if self.url is None:
128
+ return None
129
+ return self.url.get_secret_value() or None
130
+
131
+ @property
132
+ def connection_url(self) -> str:
133
+ configured = self._configured_url()
134
+ if configured is not None:
135
+ return configured
136
+ assert self.host is not None
137
+ username = quote(self.username, safe="")
138
+ password = quote(self.password.get_secret_value(), safe="")
139
+ vhost = quote(self.vhost, safe="")
140
+ return f"amqp://{username}:{password}@{self.host}:{self.port}/{vhost}"
@@ -0,0 +1,155 @@
1
+ """AMQP publisher for activity records. This module is the only one that imports aio-pika."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import logging
7
+ import socket
8
+ from collections.abc import Sequence
9
+ from typing import Final
10
+ from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
11
+ from uuid import uuid4
12
+
13
+ from unique_toolkit.experimental.resources.activity_records.config import AmqpSettings
14
+ from unique_toolkit.experimental.resources.activity_records.json_size import json_bytes
15
+ from unique_toolkit.experimental.resources.activity_records.prepare import WireEvent
16
+
17
+ try:
18
+ import aio_pika # pyright: ignore[reportMissingImports]
19
+ from aio_pika import DeliveryMode, Message # pyright: ignore[reportMissingImports]
20
+ from aio_pika.abc import ( # pyright: ignore[reportMissingImports]
21
+ AbstractExchange,
22
+ AbstractRobustConnection,
23
+ )
24
+ from aio_pika.connection import make_url # pyright: ignore[reportMissingImports]
25
+ from aio_pika.robust_channel import ( # pyright: ignore[reportMissingImports]
26
+ RobustChannel,
27
+ )
28
+ except ImportError as error: # pragma: no cover
29
+ raise ImportError(
30
+ "The AMQP publisher needs aio-pika. "
31
+ "Install it with: uv add 'unique-toolkit[activity-records-amqp]'"
32
+ ) from error
33
+
34
+ ROUTING_KEY: Final = "unique.activity-records.ingest"
35
+ DEAD_LETTER_QUEUE: Final = "unique.activity-records.ingest.dlq"
36
+ CONTENT_TYPE: Final = "application/cloudevents-batch+json"
37
+ logger = logging.getLogger(__name__)
38
+
39
+
40
+ def _connection_url(settings: AmqpSettings) -> str:
41
+ parts = urlsplit(settings.connection_url)
42
+ query = {
43
+ "heartbeat": str(settings.heartbeat_interval_in_seconds),
44
+ "name": f"{socket.gethostname()}-activity-records:publisher",
45
+ **dict(parse_qsl(parts.query)),
46
+ }
47
+ return urlunsplit(parts._replace(query=urlencode(query, safe=":")))
48
+
49
+
50
+ async def _declare_ingest_queues(channel: RobustChannel) -> None:
51
+ """Same arguments as Node's ``assertActivityIngestQueues``; a mismatch makes RabbitMQ
52
+ refuse the declaration."""
53
+ queue_options = {"durable": True, "exclusive": False, "auto_delete": False}
54
+ await channel.declare_queue(DEAD_LETTER_QUEUE, **queue_options)
55
+ await channel.declare_queue(
56
+ ROUTING_KEY,
57
+ **queue_options,
58
+ arguments={
59
+ "x-dead-letter-exchange": "",
60
+ "x-dead-letter-routing-key": DEAD_LETTER_QUEUE,
61
+ },
62
+ )
63
+
64
+
65
+ class AmqpPublisher:
66
+ """Publishes each batch to the ingest queue as one persistent message. It declares the
67
+ ingest queue and its dead letter queue before the first publish. The caller owns it:
68
+ ``connect()`` before the outbox starts, ``close()`` after it stops."""
69
+
70
+ def __init__(self, exchange: str = "") -> None:
71
+ self._exchange_name = exchange
72
+ self._connection: AbstractRobustConnection | None = None
73
+ self._channel: RobustChannel | None = None
74
+ self._connect_task: asyncio.Task[None] | None = None
75
+
76
+ async def connect(self) -> None:
77
+ """Start connecting in the background and return at once. Raises ``ValidationError``
78
+ when no broker is configured."""
79
+ if self._connection is not None:
80
+ return
81
+ settings = AmqpSettings()
82
+ connection = aio_pika.RobustConnection(
83
+ make_url(_connection_url(settings)),
84
+ fail_fast=False,
85
+ )
86
+ self._connection = connection
87
+
88
+ async def connect_in_background() -> None:
89
+ try:
90
+ await connection.connect()
91
+ except Exception as error:
92
+ logger.warning(
93
+ "Activity Records broker connection failed (%s)",
94
+ type(error).__name__,
95
+ )
96
+
97
+ self._connect_task = asyncio.create_task(connect_in_background())
98
+
99
+ async def close(self) -> None:
100
+ """Cancel the connect task and close the connection. Safe to call twice."""
101
+ task = self._connect_task
102
+ self._connect_task = None
103
+ if task is not None and not task.done():
104
+ task.cancel()
105
+ await asyncio.gather(task, return_exceptions=True)
106
+ connection = self._connection
107
+ self._connection = None
108
+ self._channel = None
109
+ if connection is not None:
110
+ await connection.close()
111
+
112
+ async def publish(self, events: Sequence[WireEvent]) -> None:
113
+ """Raises ``RuntimeError`` before ``connect()``, aio-pika's ``PublishError`` for an
114
+ unroutable message and ``DeliveryError`` for a nack. A queue declared elsewhere with
115
+ other arguments raises ``ChannelPreconditionFailed``."""
116
+ exchange = await self._exchange()
117
+ await exchange.publish(
118
+ Message(
119
+ json_bytes(events),
120
+ content_type=CONTENT_TYPE,
121
+ delivery_mode=DeliveryMode.PERSISTENT,
122
+ message_id=str(uuid4()),
123
+ ),
124
+ routing_key=ROUTING_KEY,
125
+ mandatory=True,
126
+ )
127
+
128
+ async def _exchange(self) -> AbstractExchange:
129
+ channel = await self._open_channel()
130
+ if self._exchange_name == "":
131
+ return channel.default_exchange
132
+ # ensure=False does not declare and does not passive-declare.
133
+ return await channel.get_exchange(self._exchange_name, ensure=False)
134
+
135
+ async def _open_channel(self) -> RobustChannel:
136
+ connection = self._connection
137
+ if connection is None:
138
+ raise RuntimeError("Activity records publisher is not connected")
139
+ await connection.ready()
140
+ channel = self._channel
141
+ if channel is None:
142
+ # A robust channel reopens itself after a reconnect, so it is opened once.
143
+ # aio-pika 9: on_return_raises maps a mandatory return to PublishError and a nack to DeliveryError.
144
+ opened = await connection.channel(
145
+ publisher_confirms=True, on_return_raises=True
146
+ )
147
+ assert isinstance(opened, RobustChannel)
148
+ try:
149
+ await _declare_ingest_queues(opened)
150
+ except BaseException:
151
+ await opened.close()
152
+ raise
153
+ channel = self._channel = opened
154
+ await channel.ready()
155
+ return channel
@@ -0,0 +1,30 @@
1
+ """A sender that only logs, for testing the outbox end to end."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ from collections.abc import Sequence
7
+
8
+ from unique_toolkit.experimental.resources.activity_records.json_size import json_bytes
9
+ from unique_toolkit.experimental.resources.activity_records.prepare import WireEvent
10
+
11
+ logger = logging.getLogger(__name__)
12
+
13
+
14
+ class LoggingPublisher:
15
+ """Local testing sender: logs each event and reports success without delivering it, so
16
+ the outbox rows are deleted. ``include_payload=True`` logs client data: never use it in
17
+ production."""
18
+
19
+ def __init__(self, *, include_payload: bool = False) -> None:
20
+ self.include_payload = include_payload
21
+
22
+ async def publish(self, events: Sequence[WireEvent]) -> None:
23
+ logger.info("Activity events batch: count=%d", len(events))
24
+ for event in events:
25
+ if self.include_payload:
26
+ logger.info("Activity event: %s", json_bytes(event).decode("utf-8"))
27
+ else:
28
+ logger.info(
29
+ "Activity event: id=%s type=%s", event.get("id"), event.get("type")
30
+ )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: unique-toolkit
3
- Version: 2026.48.0.dev19
3
+ Version: 2026.48.0.dev20
4
4
  Summary:
5
5
  Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
6
6
  Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
16
16
  Requires-Dist: openai>=1.105.0,<3
17
17
  Requires-Dist: platformdirs>=4.0.0,<5
18
18
  Requires-Dist: pillow>=13.0.0
19
- Requires-Dist: unique-sdk>=2026.48.0.dev17,<2026.48.0rc0
19
+ Requires-Dist: unique-sdk>=2026.48.0.dev18,<2026.48.0rc0
20
20
  Requires-Dist: jambo>=0.1.2,<0.2
21
21
  Requires-Dist: jinja2>=3.1.6,<4
22
22
  Requires-Dist: docxtpl>=0.20.1,<0.21
@@ -35,7 +35,9 @@ Requires-Dist: cachetools>=5.0,<6
35
35
  Requires-Dist: rapidfuzz>=3.0,<4
36
36
  Requires-Dist: pyyaml>=6.0.3
37
37
  Requires-Dist: asyncpg>=0.30,<1 ; extra == 'activity-records'
38
- Requires-Dist: unique-toolkit[monitoring]>=2026.48.0.dev19,<2026.48.0rc0 ; extra == 'activity-records'
38
+ Requires-Dist: unique-toolkit[monitoring]>=2026.48.0.dev20,<2026.48.0rc0 ; extra == 'activity-records'
39
+ Requires-Dist: aio-pika>=9.5.5,<10 ; extra == 'activity-records-amqp'
40
+ Requires-Dist: unique-toolkit[activity-records]>=2026.48.0.dev20,<2026.48.0rc0 ; extra == 'activity-records-amqp'
39
41
  Requires-Dist: fastapi>=0.133.0,<1.0.0 ; extra == 'fastapi'
40
42
  Requires-Dist: starlette>=1.3.1,<2.0.0 ; extra == 'fastapi'
41
43
  Requires-Dist: uvicorn>=0.37.0,<0.38 ; extra == 'fastapi'
@@ -50,6 +52,7 @@ Requires-Dist: opentelemetry-instrumentation-fastapi>=0.65b0,<1 ; extra == 'otel
50
52
  Requires-Dist: opentelemetry-instrumentation-requests>=0.65b0,<1 ; extra == 'otel'
51
53
  Requires-Python: >=3.12
52
54
  Provides-Extra: activity-records
55
+ Provides-Extra: activity-records-amqp
53
56
  Provides-Extra: fastapi
54
57
  Provides-Extra: langchain
55
58
  Provides-Extra: monitoring
@@ -361,15 +361,18 @@ unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscrib
361
361
  unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscribers/message_persister.py,sha256=JVA0lcF3_WCYEUgWqX53gO5Lj7zR1iFCCuNXuWDPGbo,8930
362
362
  unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscribers/progress_log_persister.py,sha256=VCYGZY3WSpI7mvVs2gO89-M0JenakW01BGfBfFkPDrw,3499
363
363
  unique_toolkit/experimental/resources/__init__.py,sha256=KdMPaaneY0twZ-JBfwImRjXZaWT68NVuOIeqdNXFh_Y,3377
364
- unique_toolkit/experimental/resources/activity_records/README.md,sha256=L04gy3sxzSSAA-LlsveSJ27hwAO1kM4KySfvfB1XS6w,15337
364
+ unique_toolkit/experimental/resources/activity_records/README.md,sha256=iyPFhxZRs6fd-coVAURu3qQpX5D9nbpA5bFkYiH2JFs,16570
365
365
  unique_toolkit/experimental/resources/activity_records/__init__.py,sha256=hhuMC8_HVKO38l9A9J8MFayZ_LAs7YUEmd7pWbnZtsY,548
366
- unique_toolkit/experimental/resources/activity_records/config.py,sha256=8jV6gT89zKBnHymTz_SSQbN6gfGPgK7xtKsdcZ4GA6s,3261
366
+ unique_toolkit/experimental/resources/activity_records/config.py,sha256=iggq3hnKt_c3z8bZ45MD6YFTvoimuUyU_-cCBCM6KMk,4831
367
367
  unique_toolkit/experimental/resources/activity_records/enqueue.py,sha256=uONXVBdpwtDWnoc2a6HewjA0POh4jUfoZgBnsTHr8q4,12429
368
368
  unique_toolkit/experimental/resources/activity_records/json_size.py,sha256=gfIRmI08txf0Y_wEyPTqtYrUk9FHwSouYC4R7qtdgdY,9761
369
369
  unique_toolkit/experimental/resources/activity_records/metrics.py,sha256=HuAbgEfJk658pPiswiqMAzlAL5CNYzzwGlQN73si9kA,4501
370
370
  unique_toolkit/experimental/resources/activity_records/migrate.py,sha256=LNksBdPfwRG6Xm8krShI55qA7urK19932pcuAx1xGjM,2800
371
371
  unique_toolkit/experimental/resources/activity_records/prepare.py,sha256=Q2VOqQ9S0hO1yTBGzMyCnk8AQ-UDwkIpQQlq4DQSIXo,10419
372
372
  unique_toolkit/experimental/resources/activity_records/protocols.py,sha256=pOrxKhUbj3eQx-NfnPMb6fvsHWGXwdgaqxIPRfDwN2A,611
373
+ unique_toolkit/experimental/resources/activity_records/publishers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
374
+ unique_toolkit/experimental/resources/activity_records/publishers/amqp_publisher.py,sha256=Sapea2x8nloOiOAksHWHO5rQuA01lIJGT7S2WxLU9GI,6232
375
+ unique_toolkit/experimental/resources/activity_records/publishers/logging_publisher.py,sha256=wBGjfvVfnV-lViOX8l79AGEecxActZnrnZhU49NeON4,1148
373
376
  unique_toolkit/experimental/resources/activity_records/relay.py,sha256=7md0U9HglBMjWdAvOmvsHozKDGEAI_7I-peM1IFOG74,19607
374
377
  unique_toolkit/experimental/resources/activity_records/schemas.py,sha256=6-jbRHJrqOjbPp9ij1etpbZjKZ6ol-TiE60vdiDkqJA,6864
375
378
  unique_toolkit/experimental/resources/activity_records/store.py,sha256=is-tESmoo-ox7nY6WrIOXdqe8UH1QsLTydoIXxtB8WA,13342
@@ -447,6 +450,6 @@ unique_toolkit/short_term_memory/service.py,sha256=2JMBEBn6GoyK-a0xvdcWpPft-3C74
447
450
  unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
448
451
  unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
449
452
  unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
450
- unique_toolkit-2026.48.0.dev19.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
451
- unique_toolkit-2026.48.0.dev19.dist-info/METADATA,sha256=K9HofFJ6Uhb8lf7YRbj5JkCNetuJKr527tAPr7cSEiM,8021
452
- unique_toolkit-2026.48.0.dev19.dist-info/RECORD,,
453
+ unique_toolkit-2026.48.0.dev20.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
454
+ unique_toolkit-2026.48.0.dev20.dist-info/METADATA,sha256=0XqYeMGX1hsSccvS3XM0UpX_H8b9nBwXXxqS0TnCszI,8243
455
+ unique_toolkit-2026.48.0.dev20.dist-info/RECORD,,