unique_toolkit 2026.48.0.dev13__py3-none-any.whl → 2026.48.0.dev15__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.
- unique_toolkit/agentic/loop_runner/middleware/planning/planning.py +1 -0
- unique_toolkit/chat/responses_api.py +4 -0
- unique_toolkit/experimental/integrations/openai/streaming/event_routing/_model_params.py +20 -13
- unique_toolkit/experimental/integrations/openai/streaming/event_routing/responses/complete_with_references.py +2 -1
- unique_toolkit/experimental/resources/activity_records/README.md +284 -0
- unique_toolkit/experimental/resources/activity_records/__init__.py +8 -1
- unique_toolkit/experimental/resources/activity_records/config.py +4 -0
- unique_toolkit/experimental/resources/activity_records/enqueue.py +342 -0
- unique_toolkit/experimental/resources/activity_records/metrics.py +135 -0
- unique_toolkit/experimental/resources/activity_records/prepare.py +5 -0
- unique_toolkit/experimental/resources/activity_records/protocols.py +21 -0
- unique_toolkit/experimental/resources/activity_records/relay.py +526 -0
- unique_toolkit/language_model/functions.py +5 -0
- unique_toolkit/language_model/infos.py +106 -0
- unique_toolkit/monitoring/registry.py +18 -5
- {unique_toolkit-2026.48.0.dev13.dist-info → unique_toolkit-2026.48.0.dev15.dist-info}/METADATA +2 -2
- {unique_toolkit-2026.48.0.dev13.dist-info → unique_toolkit-2026.48.0.dev15.dist-info}/RECORD +18 -13
- {unique_toolkit-2026.48.0.dev13.dist-info → unique_toolkit-2026.48.0.dev15.dist-info}/WHEEL +0 -0
|
@@ -232,6 +232,7 @@ class ResponsesPlanningMiddleware(ResponsesLoopIterationRunner):
|
|
|
232
232
|
|
|
233
233
|
other_options = kwargs.get("other_options") or {}
|
|
234
234
|
forwarded.update({k: v for k, v in other_options.items() if k not in ignored})
|
|
235
|
+
kwargs["model"].drop_unsupported_options(forwarded)
|
|
235
236
|
return forwarded
|
|
236
237
|
|
|
237
238
|
def _build_tools(
|
|
@@ -372,6 +372,10 @@ def _prepare_responses_args(
|
|
|
372
372
|
for k, v in strip_translated_responses_options(other_options).items():
|
|
373
373
|
openai_options.setdefault(k, v) # pyright: ignore[reportCallIssue, reportArgumentType]
|
|
374
374
|
|
|
375
|
+
LanguageModelInfo.from_name(params.model_name).drop_unsupported_options(
|
|
376
|
+
openai_options # pyright: ignore[reportArgumentType]
|
|
377
|
+
)
|
|
378
|
+
|
|
375
379
|
options["options"] = openai_options
|
|
376
380
|
|
|
377
381
|
return options
|
|
@@ -24,11 +24,12 @@ def prepare_chat_completions_model_params(
|
|
|
24
24
|
temperature: float,
|
|
25
25
|
other_options: dict[str, Any] | None,
|
|
26
26
|
) -> dict[str, Any]:
|
|
27
|
-
"""Prepare Chat Completions create() options
|
|
27
|
+
"""Prepare Chat Completions create() options for the model.
|
|
28
28
|
|
|
29
29
|
Copies ``other_options`` so the caller dict is not mutated, applies
|
|
30
30
|
``LanguageModelInfo`` temperature/reasoning rules, and writes the clamped
|
|
31
|
-
temperature onto the returned options dict
|
|
31
|
+
temperature onto the returned options dict when the model supports
|
|
32
|
+
sampling parameters.
|
|
32
33
|
|
|
33
34
|
Args:
|
|
34
35
|
model_name (LanguageModelName | str): Model identifier from the caller.
|
|
@@ -36,18 +37,21 @@ def prepare_chat_completions_model_params(
|
|
|
36
37
|
other_options (dict[str, Any] | None): Extra OpenAI create() kwargs.
|
|
37
38
|
|
|
38
39
|
Returns:
|
|
39
|
-
dict[str, Any]: Sanitized create() options
|
|
40
|
+
dict[str, Any]: Sanitized create() options. ``temperature`` is included
|
|
41
|
+
only when the model supports sampling parameters.
|
|
40
42
|
"""
|
|
41
43
|
options = dict(other_options) if other_options else {}
|
|
42
44
|
requested_effort = options.get("reasoning_effort")
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
45
|
+
model_info = LanguageModelInfo.from_name(model_name)
|
|
46
|
+
temperature, resolved_effort = model_info.resolve_temp_and_reasoning(
|
|
47
|
+
temperature, requested_effort
|
|
48
|
+
)
|
|
46
49
|
if resolved_effort is not None:
|
|
47
50
|
options["reasoning_effort"] = resolved_effort
|
|
48
51
|
else:
|
|
49
52
|
options.pop("reasoning_effort", None)
|
|
50
53
|
options["temperature"] = temperature
|
|
54
|
+
model_info.drop_unsupported_options(options)
|
|
51
55
|
return options
|
|
52
56
|
|
|
53
57
|
|
|
@@ -58,15 +62,15 @@ def prepare_responses_model_params(
|
|
|
58
62
|
other_options: dict[str, Any] | None,
|
|
59
63
|
tools: Sequence[Mapping[str, Any]] | None = None,
|
|
60
64
|
) -> dict[str, Any]:
|
|
61
|
-
"""Prepare Responses API create() options
|
|
65
|
+
"""Prepare Responses API create() options for the model.
|
|
62
66
|
|
|
63
67
|
Extracts reasoning from ``other_options`` when the explicit argument is
|
|
64
68
|
missing (UniqueAI passes ``reasoning`` that way), applies
|
|
65
69
|
``LanguageModelInfo`` bounds, and bumps ``minimal`` effort to ``low`` when
|
|
66
70
|
a code-interpreter tool is present. Chat-completions ``reasoning_effort`` /
|
|
67
71
|
``verbosity`` are mapped to ``reasoning`` / ``text`` and not forwarded
|
|
68
|
-
verbatim.
|
|
69
|
-
|
|
72
|
+
verbatim. Reasoning and text are written onto the returned options dict,
|
|
73
|
+
and the clamped temperature when the model supports sampling parameters.
|
|
70
74
|
|
|
71
75
|
Args:
|
|
72
76
|
model_name (LanguageModelName | str): Model identifier from the caller.
|
|
@@ -76,7 +80,8 @@ def prepare_responses_model_params(
|
|
|
76
80
|
tools (Sequence[Mapping[str, Any]] | None): Converted Responses tools.
|
|
77
81
|
|
|
78
82
|
Returns:
|
|
79
|
-
dict[str, Any]: Sanitized create() options
|
|
83
|
+
dict[str, Any]: Sanitized create() options. ``temperature`` is included
|
|
84
|
+
only when the model supports sampling parameters.
|
|
80
85
|
"""
|
|
81
86
|
raw_options = dict(other_options) if other_options else {}
|
|
82
87
|
if reasoning is None:
|
|
@@ -85,9 +90,10 @@ def prepare_responses_model_params(
|
|
|
85
90
|
options = strip_translated_responses_options(raw_options)
|
|
86
91
|
|
|
87
92
|
requested_effort = reasoning.get("effort") if reasoning is not None else None
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
93
|
+
model_info = LanguageModelInfo.from_name(model_name)
|
|
94
|
+
temperature, resolved_effort = model_info.resolve_temp_and_reasoning(
|
|
95
|
+
temperature, requested_effort
|
|
96
|
+
)
|
|
91
97
|
reasoning = _bump_code_interpreter_effort(
|
|
92
98
|
_apply_resolved_reasoning(reasoning, resolved_effort),
|
|
93
99
|
tools,
|
|
@@ -97,6 +103,7 @@ def prepare_responses_model_params(
|
|
|
97
103
|
options["reasoning"] = reasoning
|
|
98
104
|
if text is not None:
|
|
99
105
|
options["text"] = text
|
|
106
|
+
model_info.drop_unsupported_options(options)
|
|
100
107
|
return options
|
|
101
108
|
|
|
102
109
|
|
|
@@ -30,7 +30,7 @@ from unique_toolkit.experimental._internal.streaming.pattern_replacer import (
|
|
|
30
30
|
)
|
|
31
31
|
from unique_toolkit.framework_utilities.openai.client import get_async_openai_client
|
|
32
32
|
from unique_toolkit.language_model.constants import DEFAULT_COMPLETE_TEMPERATURE
|
|
33
|
-
from unique_toolkit.language_model.infos import LanguageModelName
|
|
33
|
+
from unique_toolkit.language_model.infos import LanguageModelInfo, LanguageModelName
|
|
34
34
|
from unique_toolkit.language_model.schemas import (
|
|
35
35
|
LanguageModelMessageOptions,
|
|
36
36
|
LanguageModelMessages,
|
|
@@ -544,6 +544,7 @@ class ResponsesCompleteWithReferences(ResponsesSupportCompleteWithReferences):
|
|
|
544
544
|
create_kwargs["top_p"] = top_p
|
|
545
545
|
for k, v in other_options.items():
|
|
546
546
|
create_kwargs.setdefault(k, v)
|
|
547
|
+
LanguageModelInfo.from_name(model_name).drop_unsupported_options(create_kwargs)
|
|
547
548
|
gpt_request: dict[str, Any] = {
|
|
548
549
|
"model": model,
|
|
549
550
|
"input": converted_messages,
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Activity Records outbox
|
|
2
|
+
This library records validated Activity Records events in the producer's own
|
|
3
|
+
Postgres database and relays them through a sender the caller supplies. It
|
|
4
|
+
prepares events synchronously, stores them in a background task, and retries
|
|
5
|
+
failed deliveries. Rows are deleted only after the sender returns without raising,
|
|
6
|
+
or when the flag client's remote read says the company is off. A cached off defers
|
|
7
|
+
the rows until the cache expires and a remote read answers.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
enqueue(event) -> ActivityEventOutbox table -> OutboxRelay -> sender
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This is a port of the Node `@unique/activity-events-client` as on its master
|
|
14
|
+
branch: PR #33463 (merged) plus the follow-up #34009. It is experimental and
|
|
15
|
+
the interface may change.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
```sh
|
|
19
|
+
uv add 'unique-toolkit[activity-records]'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The extra installs asyncpg and prometheus_client. Also install `opentelemetry-api`
|
|
23
|
+
(or the `otel` extra) so events get their correlationId from the active trace.
|
|
24
|
+
|
|
25
|
+
## Migration
|
|
26
|
+
Run the idempotent migration before the application starts:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python -m unique_toolkit.experimental.resources.activity_records.migrate
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`DATABASE_URL` is required. The command exits non-zero, with a message that names the
|
|
33
|
+
table and no values, when the table exists but a column is missing or has a wrong
|
|
34
|
+
type. Extra columns are allowed. Run this command from a Helm
|
|
35
|
+
`pre-install,pre-upgrade` hook, not from application startup.
|
|
36
|
+
|
|
37
|
+
## Configuration
|
|
38
|
+
Required database variable:
|
|
39
|
+
|
|
40
|
+
- `DATABASE_URL`: asyncpg reads its query parameters. `sslmode=verify` becomes
|
|
41
|
+
`verify-full` and `connect_timeout` becomes the connect timeout. `application_name`
|
|
42
|
+
is kept. Any other parameter asyncpg does not read, such as Prisma's `schema=` or
|
|
43
|
+
`connection_limit=`, is dropped and only its name is logged once.
|
|
44
|
+
|
|
45
|
+
Size settings are `ACTIVITY_RECORDS_MAX_DATA_SIZE_BYTES` and
|
|
46
|
+
`ACTIVITY_RECORDS_MAX_BATCH_SIZE_BYTES`, defaulting to 1 MiB and 8 MiB.
|
|
47
|
+
|
|
48
|
+
The default feature flag client needs `CONFIGURATION_BACKEND_URL`,
|
|
49
|
+
`FEATURE_FLAG_SERVICE_ID`, and optionally `FEATURE_FLAG_CACHE_TTL_MS`. The flag
|
|
50
|
+
is `FEATURE_FLAG_ENABLE_ACTIVITY_RECORDS_EVENTS_UN_22616`. Keep
|
|
51
|
+
`FEATURE_FLAG_CACHE_TTL_MS` at 5000 or less, because the write path skips an insert
|
|
52
|
+
on a cached off. When no flag client is injected, the write path uses the shared
|
|
53
|
+
`FeatureFlagClient` and the relay builds its own instance from the same settings.
|
|
54
|
+
The relay needs its own cache: callers that keep the shared cache warm would hide
|
|
55
|
+
every remote read, and only a remote off deletes rows. An injected flag client is
|
|
56
|
+
used for both, so it must not share a cache that other callers keep warm.
|
|
57
|
+
|
|
58
|
+
## Sender
|
|
59
|
+
Delivery is done by a sender the caller supplies (`PublisherLike`):
|
|
60
|
+
`async publish(events: list[dict]) -> None`. Raise a `TimeoutError` subclass on
|
|
61
|
+
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.
|
|
63
|
+
|
|
64
|
+
## FastAPI
|
|
65
|
+
Create one runtime and start and stop it in the FastAPI lifespan:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
from contextlib import asynccontextmanager
|
|
69
|
+
|
|
70
|
+
from fastapi import FastAPI
|
|
71
|
+
from unique_toolkit.experimental.resources.activity_records import ActivityRecordsOutbox
|
|
72
|
+
|
|
73
|
+
runtime = ActivityRecordsOutbox(publisher=my_sender)
|
|
74
|
+
|
|
75
|
+
@asynccontextmanager
|
|
76
|
+
async def lifespan(_app: FastAPI):
|
|
77
|
+
await runtime.start()
|
|
78
|
+
try:
|
|
79
|
+
yield
|
|
80
|
+
finally:
|
|
81
|
+
await runtime.stop()
|
|
82
|
+
|
|
83
|
+
app = FastAPI(lifespan=lifespan)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Use `runtime.is_ready()` for the service readiness probe. It answers false until
|
|
87
|
+
the relay's schema check passes, then stays true, also while the database is down
|
|
88
|
+
(the relay keeps polling and logs the errors). The check re-runs every 10 seconds,
|
|
89
|
+
like Node. An error during the check is logged once per outage as an
|
|
90
|
+
unreachable database, and only a real column mismatch is logged as a missing table.
|
|
91
|
+
|
|
92
|
+
## Enqueue an event
|
|
93
|
+
```python
|
|
94
|
+
from unique_toolkit.experimental.resources.activity_records import (
|
|
95
|
+
ActivityActor,
|
|
96
|
+
ActivityCloudEvent,
|
|
97
|
+
ActivityEventData,
|
|
98
|
+
enqueue,
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
event = ActivityCloudEvent(
|
|
102
|
+
source="web-search",
|
|
103
|
+
type="web-search.tool.called",
|
|
104
|
+
data=ActivityEventData(
|
|
105
|
+
actor=ActivityActor(id="user-1", type="user"),
|
|
106
|
+
company_id="company-1",
|
|
107
|
+
),
|
|
108
|
+
)
|
|
109
|
+
enqueue(event)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The constructor rejects metadata over its length limit (identifier 128, ip 64,
|
|
113
|
+
text 256 UTF-16 units). `ActivityCloudEvent.build(source=..., type=..., data={...})`
|
|
114
|
+
shortens such values instead, so a long name never drops the record. It counts
|
|
115
|
+
the event as `truncated`, lists the fields in `event.truncated_fields` and logs a
|
|
116
|
+
warning with the event type, the source and the field paths (never the values).
|
|
117
|
+
The paths are wire paths like Node's, for example `actor.id`, `agent.id` and `targetName`.
|
|
118
|
+
Producers should build events with `build`.
|
|
119
|
+
|
|
120
|
+
`enqueue` is synchronous for the caller and never raises. Call it from the
|
|
121
|
+
event-loop thread. Preparing an event (validation, sizing, truncation) is CPU bound
|
|
122
|
+
and runs synchronously on the event loop, like Node's. It is best effort:
|
|
123
|
+
the prepared insert runs in a background task, and normal shutdown drains
|
|
124
|
+
pending inserts for up to 10 seconds. Delivery is at least once. The insert
|
|
125
|
+
does not wait for the relay's table check; a missing or mismatched table fails
|
|
126
|
+
the insert and counts a record failure. It waits at most 5 seconds for the
|
|
127
|
+
database pool to exist. Waiting for a free connection is bounded by the 40 second
|
|
128
|
+
insert timeout. `enqueue` skips the insert when a fresh or cached flag read says
|
|
129
|
+
off. After a failed flag read (including the 5 second timeout) a company is not
|
|
130
|
+
asked again for 15 seconds and its events are inserted; the relay checks the
|
|
131
|
+
flag again before delivery and defers when it is unknown. A stale or fallback answer
|
|
132
|
+
starts the same pause. At most 1000 inserts wait at once; further events are dropped
|
|
133
|
+
and counted in `record_failures`.
|
|
134
|
+
|
|
135
|
+
Events are lost, and counted in `record_failures`, when the insert fails. A refused
|
|
136
|
+
connection loses the event at once. The 5 seconds cover only the wait for the
|
|
137
|
+
database pool. An insert on a frozen database fails after at most 40 seconds (10
|
|
138
|
+
seconds to connect and 30 seconds per command; the insert call is limited to 40
|
|
139
|
+
seconds). Events are also lost when the process exits before the background
|
|
140
|
+
insert runs (not counted). An `enqueue` call while no outbox is running (before
|
|
141
|
+
`start()`, or while `stop()` runs) logs "no Activity Records outbox is running" and
|
|
142
|
+
counts in `record_failures` once an outbox has run in the process.
|
|
143
|
+
|
|
144
|
+
When the flag is off at `enqueue`, the insert is skipped without a metric or a log,
|
|
145
|
+
like Node's best effort write. The 15 second pause on flag reads starts when the
|
|
146
|
+
5 second wait expires, the flag client raises, or it answers stale or fallback. The
|
|
147
|
+
default flag client never raises: when a request fails or exceeds its own 2 second
|
|
148
|
+
timeout (1 second to connect) it returns a fallback or stale answer, which
|
|
149
|
+
the write path treats as unknown and inserts the event.
|
|
150
|
+
|
|
151
|
+
## criticalData size limit
|
|
152
|
+
An event's `data` may not exceed `ACTIVITY_RECORDS_MAX_DATA_SIZE_BYTES` (1 MiB by
|
|
153
|
+
default). When it does, `criticalData` is cut to fit: strings are shortened, keys
|
|
154
|
+
and array items can be dropped, and `criticalData.truncated` is set to true. The
|
|
155
|
+
event is counted as `truncated`. A value nested deeper than 200 levels is cut the same
|
|
156
|
+
way: the part below that depth becomes null and `criticalData.truncated` marks it too.
|
|
157
|
+
|
|
158
|
+
## Kill switch
|
|
159
|
+
When the relay reads a company's flag as off from the remote, it deletes that
|
|
160
|
+
company's queued rows without publishing them and counts them in
|
|
161
|
+
`unique_activity_event_outbox_discarded_total`. This also hits events recorded while
|
|
162
|
+
the flag was on. The configuration backend answers false for a flag key it does not
|
|
163
|
+
know, so a flag key that does not exist reads as off and deletes every queued event
|
|
164
|
+
of every company. Roll out in this order: release the code that reads the flag,
|
|
165
|
+
create the flag, and only then enable it. To retire the flag, remove the flag check
|
|
166
|
+
from the service first and the key from the registry afterwards.
|
|
167
|
+
|
|
168
|
+
## Personal data in the outbox
|
|
169
|
+
The `payload` column holds the full event, including `criticalData` (for web search
|
|
170
|
+
the user prompt and the tool arguments). It is a second store of personal data and
|
|
171
|
+
is not covered by the data redaction job. A healthy outbox holds seconds of it. A
|
|
172
|
+
stuck row stays until it is delivered. Company deletion does not purge outbox rows.
|
|
173
|
+
|
|
174
|
+
## Rolling back
|
|
175
|
+
A rollback never removes the table. Queued rows stay, and nothing delivers them
|
|
176
|
+
while the service runs without this library. Wait for
|
|
177
|
+
`unique_activity_event_outbox_pending_rows` to reach 0 before rolling back.
|
|
178
|
+
|
|
179
|
+
## Settings
|
|
180
|
+
`ACTIVITY_RECORDS_MAX_DATA_SIZE_BYTES` and `ACTIVITY_RECORDS_MAX_BATCH_SIZE_BYTES`
|
|
181
|
+
are read by the activity-records intake too. If you override either, override it on
|
|
182
|
+
both sides. A missing value uses the default and a numeric string is accepted. A
|
|
183
|
+
value that is not a number, or a batch size too small for the data size, makes
|
|
184
|
+
`start()` raise before anything is created, like Node's assert at construction.
|
|
185
|
+
|
|
186
|
+
The relay's timings are fixed, like Node's. It claims up to 100 rows under a 90
|
|
187
|
+
second lease and publishes nothing after half of it. It polls every second when idle
|
|
188
|
+
and waits 5 seconds for a flag answer and 30 seconds for the sender. Rows whose flag
|
|
189
|
+
cannot be read are deferred by 15 to 30 seconds (30 seconds with 50 to 100 percent
|
|
190
|
+
jitter), and that company is not asked again for 15 seconds. Gauges refresh every 15
|
|
191
|
+
seconds and keep their last value if a refresh fails. The relay claims again at once
|
|
192
|
+
only after settling a full batch; a round that only deferred rows waits the idle
|
|
193
|
+
poll. On shutdown the relay stops and hands its rows back, then pending inserts get
|
|
194
|
+
10 seconds, then the pool closes (terminated after 5 seconds if the database does
|
|
195
|
+
not answer).
|
|
196
|
+
|
|
197
|
+
## Alerts
|
|
198
|
+
The Helm library chart `charts/activity-events-client` ships the alerts for the
|
|
199
|
+
outbox metrics. A service that uses this library includes that chart and sets
|
|
200
|
+
`activityEventsClient.metricName` to the `metric_name` used in code (default
|
|
201
|
+
`unique_activity_events_total`). Keep `tableAlerts` true on exactly one deployable
|
|
202
|
+
per outbox table. The backoff cap alert is critical. Do not write alerts on these
|
|
203
|
+
metrics by hand in `prometheus.additionalAlerts`, because the chart already renders
|
|
204
|
+
them and a copy fires twice. Add the chart directory to the service's CI path
|
|
205
|
+
filters and sparse checkout. The alert texts mention RabbitMQ today; read it as the
|
|
206
|
+
sender. A `timeout` publish failure means the sender raised a `TimeoutError` or took
|
|
207
|
+
longer than 30 seconds, and `rejected` means any other exception.
|
|
208
|
+
The alert texts need new wording when the GraphQL sender replaces RabbitMQ.
|
|
209
|
+
|
|
210
|
+
## Readiness and migration
|
|
211
|
+
Run the migration as a Helm pre-install and pre-upgrade hook so there is no deploy
|
|
212
|
+
order problem. Extra columns are allowed, so a rollback onto a newer migration keeps
|
|
213
|
+
working. Until the schema check passes the relay does not run and `is_ready()` is
|
|
214
|
+
false.
|
|
215
|
+
|
|
216
|
+
## Metrics
|
|
217
|
+
- `unique_activity_events_total{outcome,source,actorType,eventType}`
|
|
218
|
+
- `unique_activity_event_outbox_record_failures_total`
|
|
219
|
+
- `unique_activity_event_outbox_publish_failures_total{reason}`
|
|
220
|
+
- `unique_activity_event_outbox_backoff_max_reached_total`
|
|
221
|
+
- `unique_activity_event_outbox_discarded_total`
|
|
222
|
+
- `unique_activity_event_outbox_invalid_events_total`
|
|
223
|
+
- `unique_activity_event_outbox_flag_check_failures_total`
|
|
224
|
+
- `unique_activity_event_outbox_pending_rows`
|
|
225
|
+
- `unique_activity_event_outbox_oldest_pending_age_seconds`
|
|
226
|
+
- `unique_activity_event_outbox_rows_at_max_backoff`
|
|
227
|
+
|
|
228
|
+
The metrics use the toolkit's private registry. The host must serve
|
|
229
|
+
`unique_toolkit.monitoring.get_metrics()` on the `/metrics` path that Prometheus
|
|
230
|
+
scrapes. The three gauges (`pending_rows`, `oldest_pending_age_seconds`, `rows_at_max_backoff`)
|
|
231
|
+
are table-wide, so every worker reports the same value; in multiprocess mode they use
|
|
232
|
+
`livemax` to keep one series. Publish failure reasons are `timeout` and `rejected`. A publish that fails while
|
|
233
|
+
the relay is stopping is neither counted nor backed off, because `stop()` hands the
|
|
234
|
+
rows back. A sender call that takes longer than 30 seconds counts as a timeout. A
|
|
235
|
+
rejected batch is retried row by row, like Node, so a rejecting sender gets one
|
|
236
|
+
call per row.
|
|
237
|
+
|
|
238
|
+
## Operations
|
|
239
|
+
The outbox table belongs to the producer's database. There is no TTL or cleanup
|
|
240
|
+
job. A row the sender keeps rejecting retries forever, with a 15 minute cap,
|
|
241
|
+
and needs manual deletion. Every retry delay is jittered to 50 to 100 percent, so a
|
|
242
|
+
retry at the cap comes after 7.5 to 15 minutes.
|
|
243
|
+
|
|
244
|
+
## Differences from the Node library
|
|
245
|
+
- A stale "on" flag is treated as on.
|
|
246
|
+
- The flag client has no cache bypass argument. Node deletes after an uncached read; here
|
|
247
|
+
a cached off only defers, and a delete needs an off from the remote read.
|
|
248
|
+
- Node answers an unknown flag with a rejection. The Python flag client returns a fallback
|
|
249
|
+
or stale answer instead, and the relay treats both as unknown. The write path starts its
|
|
250
|
+
15 second pause on such an answer too, as on an error or the 5 second timeout.
|
|
251
|
+
- The write path has no 5 second cache of its own; it reads through the flag client's
|
|
252
|
+
cache on every insert, except for 15 seconds after a failed, stale or fallback read,
|
|
253
|
+
when it skips the read and inserts.
|
|
254
|
+
- The pool has a 30 second command timeout and a 10 second connect timeout, and an insert
|
|
255
|
+
task is limited to 40 seconds. Node has none of these.
|
|
256
|
+
- `stop()` terminates a pool that does not close within 5 seconds, and cancels the running
|
|
257
|
+
round after 5 seconds where Node only stops waiting for it.
|
|
258
|
+
- `start()` returns before the first schema check, so `is_ready()` is false right after
|
|
259
|
+
it; Node awaits the first check.
|
|
260
|
+
- A failed schema check is logged once per outage as an unreachable database and never as
|
|
261
|
+
a mismatch; Node warns on every failed check.
|
|
262
|
+
- The write path awaits a flag read of up to 5 seconds in the background insert task
|
|
263
|
+
before inserting; Node decides synchronously from its own cache, records on unknown and
|
|
264
|
+
refreshes in the background.
|
|
265
|
+
- `sslmode=verify` in `DATABASE_URL` is translated to asyncpg's `verify-full`.
|
|
266
|
+
- The migration connection has a 60 second command timeout, so a held advisory lock or a
|
|
267
|
+
stuck DDL statement fails the Helm hook instead of waiting forever. Node has none.
|
|
268
|
+
- `prepare_rows` rejects a company id that sanitization would change and an event of
|
|
269
|
+
another company; Node sanitizes and does not compare.
|
|
270
|
+
- The relay times out a sender call after 30 seconds; Node's publisher has its own 30
|
|
271
|
+
second confirm timeout.
|
|
272
|
+
- The relay builds its own flag client when none is injected (see Configuration); Node's
|
|
273
|
+
relay and write path share the host's `isEnabled`.
|
|
274
|
+
- There is no `record_in_transaction`.
|
|
275
|
+
- The relay's schema check uses the same strict keys as zod, but parses the event id and
|
|
276
|
+
time more leniently: an id without hyphens or a time with a numeric offset such as
|
|
277
|
+
`+00:00` still passes.
|
|
278
|
+
- The JSON nesting depth limit is 200 (Node: 500).
|
|
279
|
+
- Numbers are sized as Postgres jsonb prints them, because Python reads payloads back with
|
|
280
|
+
`json.loads`: a float with an exponent, such as `1e300`, comes back as a long integer.
|
|
281
|
+
Node does not need this.
|
|
282
|
+
- `ActivityCloudEvent.truncated_fields` and the truncation warning use wire paths like
|
|
283
|
+
Node (`actor.id`, `targetName`).
|
|
284
|
+
- No broker publisher in this package yet.
|
|
@@ -1,5 +1,7 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""Public API for the experimental Activity Records outbox."""
|
|
2
2
|
|
|
3
|
+
from .enqueue import ActivityRecordsOutbox, drain, enqueue, is_running
|
|
4
|
+
from .relay import OutboxRelay
|
|
3
5
|
from .schemas import (
|
|
4
6
|
ACTIVITY_METADATA_MAX_LENGTH,
|
|
5
7
|
ActivityActor,
|
|
@@ -14,4 +16,9 @@ __all__ = [
|
|
|
14
16
|
"ActivityAgent",
|
|
15
17
|
"ActivityCloudEvent",
|
|
16
18
|
"ActivityEventData",
|
|
19
|
+
"ActivityRecordsOutbox",
|
|
20
|
+
"OutboxRelay",
|
|
21
|
+
"drain",
|
|
22
|
+
"enqueue",
|
|
23
|
+
"is_running",
|
|
17
24
|
]
|
|
@@ -16,7 +16,11 @@ from unique_toolkit.experimental.resources.activity_records.schemas import (
|
|
|
16
16
|
|
|
17
17
|
DEFAULT_MAX_DATA_SIZE_BYTES: Final = 1_048_576
|
|
18
18
|
DEFAULT_MAX_BATCH_SIZE_BYTES: Final = 8_388_608
|
|
19
|
+
FEATURE_FLAG_ENABLE_ACTIVITY_RECORDS_EVENTS_UN_22616: Final = (
|
|
20
|
+
"FEATURE_FLAG_ENABLE_ACTIVITY_RECORDS_EVENTS_UN_22616"
|
|
21
|
+
)
|
|
19
22
|
OUTBOX_MAX_BACKOFF_ATTEMPTS: Final = 11
|
|
23
|
+
DEFAULT_ACTIVITY_EVENTS_METRIC_NAME: Final = "unique_activity_events_total"
|
|
20
24
|
ACTIVITY_RECORDS_INSTALL_HINT: Final = (
|
|
21
25
|
"Install it with: uv add 'unique-toolkit[activity-records]'"
|
|
22
26
|
)
|