agentdevlabs 0.1.0__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.
@@ -0,0 +1,7 @@
1
+ from agentdevlabs import events
2
+ from agentdevlabs.cache_key import cache_key
3
+ from agentdevlabs.hook import wrap
4
+ from agentdevlabs.redact import redact
5
+ from agentdevlabs.trace import trace
6
+
7
+ __all__ = ["cache_key", "events", "redact", "trace", "wrap"]
@@ -0,0 +1,466 @@
1
+ # generated by datamodel-codegen:
2
+ # filename: openapi.json
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import Any, Dict, List, Literal, NotRequired, Optional, TypedDict, Union
7
+
8
+
9
+ class CallOut(TypedDict):
10
+ capture_id: str
11
+ cost_micros: Optional[int]
12
+ created_at: str
13
+ duration_ms: Optional[int]
14
+ input_tokens: Optional[int]
15
+ is_stream: bool
16
+ model: str
17
+ output_tokens: Optional[int]
18
+ provider: str
19
+ size_bytes: int
20
+ status: Literal['complete', 'aborted', 'error']
21
+ step: int
22
+ ttfb_ms: Optional[int]
23
+
24
+
25
+ class CaptureOut(TypedDict):
26
+ cache_key: str
27
+ capture_id: str
28
+ download_url: Optional[str]
29
+ is_stream: bool
30
+ key: str
31
+ model: str
32
+ provider: str
33
+ step: int
34
+
35
+
36
+ class CaptureStored(TypedDict):
37
+ capture_id: str
38
+
39
+
40
+ class CliLoginApproveIn(TypedDict):
41
+ environment_id: str
42
+ user_code: str
43
+ workspace_id: str
44
+
45
+
46
+ class CliLoginApproved(TypedDict):
47
+ redirect_url: NotRequired[Optional[str]]
48
+
49
+
50
+ class CliLoginCollectIn(TypedDict):
51
+ authorization_code: NotRequired[Optional[str]]
52
+ code_verifier: NotRequired[Optional[str]]
53
+ device_code: NotRequired[Optional[str]]
54
+
55
+
56
+ class CliLoginOut(TypedDict):
57
+ client: Literal['cli', 'devkit']
58
+ expires_at: str
59
+ flow: Literal['code', 'callback']
60
+ hostname: str
61
+
62
+
63
+ class CliLoginStart(TypedDict):
64
+ callback_port: NotRequired[Optional[int]]
65
+ client: NotRequired[Literal['cli', 'devkit']]
66
+ code_challenge: NotRequired[Optional[str]]
67
+ hostname: str
68
+ state: NotRequired[Optional[str]]
69
+
70
+
71
+ class CliLoginStarted(TypedDict):
72
+ approve_url: str
73
+ device_code: NotRequired[Optional[str]]
74
+ expires_in: int
75
+ interval: NotRequired[Optional[int]]
76
+ user_code: str
77
+
78
+
79
+ class CliToken(TypedDict):
80
+ environment_name: str
81
+ expires_at: str
82
+ project_name: str
83
+ token: str
84
+ workspace_name: str
85
+
86
+
87
+ class DailyUsageOut(TypedDict):
88
+ captures: int
89
+ cost_avoided_micros: int
90
+ day: str
91
+ environment_id: str
92
+ errors: int
93
+ hits: int
94
+ latency_saved_ms: int
95
+ misses: int
96
+
97
+
98
+ class EnvironmentIn(TypedDict):
99
+ is_production: bool
100
+ name: str
101
+
102
+
103
+ class EnvironmentOut(TypedDict):
104
+ default_mode: str
105
+ id: str
106
+ is_production: bool
107
+ name: str
108
+
109
+
110
+ class EnvironmentPatch(TypedDict):
111
+ default_mode: Literal['auto', 'capture', 'replay', 'off']
112
+
113
+
114
+ class EventIn(TypedDict):
115
+ cache_key: str
116
+ capture_id: NotRequired[Optional[str]]
117
+ drift: NotRequired[bool]
118
+ latency_ms: int
119
+ status: Literal['hit', 'miss', 'capture', 'error']
120
+ trace_id: NotRequired[Optional[str]]
121
+
122
+
123
+ class EventOut(TypedDict):
124
+ at: str
125
+ cost_micros: Optional[int]
126
+ drift: bool
127
+ environment_id: str
128
+ id: str
129
+ input_tokens: Optional[int]
130
+ latency_ms: int
131
+ model: Optional[str]
132
+ output_tokens: Optional[int]
133
+ provider: Optional[str]
134
+ status: str
135
+ trace_id: Optional[str]
136
+
137
+
138
+ class FirstToken(TypedDict):
139
+ env_line: str
140
+ environment_id: str
141
+ token: str
142
+ workspace_id: str
143
+
144
+
145
+ class GroupIn(TypedDict):
146
+ name: str
147
+ purpose: NotRequired[Optional[str]]
148
+
149
+
150
+ class GroupOrderIn(TypedDict):
151
+ trace_ids: List[str]
152
+
153
+
154
+ class GroupOut(TypedDict):
155
+ id: str
156
+ name: str
157
+ project_id: str
158
+ purpose: Optional[str]
159
+ trace_count: int
160
+
161
+
162
+ class GroupTraceIn(TypedDict):
163
+ trace_id: str
164
+
165
+
166
+ class GroupTraceOut(TypedDict):
167
+ environment_id: str
168
+ environment_name: str
169
+ id: str
170
+ model: Optional[str]
171
+ position: int
172
+ provider: Optional[str]
173
+ recorded_at: str
174
+ steps: int
175
+
176
+
177
+ class HealthOut(TypedDict):
178
+ status: Literal['ok', 'unavailable']
179
+
180
+
181
+ class LeakVerdict(TypedDict):
182
+ label: Literal['true_positive', 'false_positive']
183
+ token_raw: str
184
+ token_type: str
185
+
186
+
187
+ class MediaPart(TypedDict):
188
+ bytes: NotRequired[Optional[int]]
189
+ media_type: str
190
+ type: NotRequired[Literal['media']]
191
+
192
+
193
+ class ModeOut(TypedDict):
194
+ mode: Literal['auto', 'capture', 'replay', 'off']
195
+ off_reason: Optional[Literal['production', 'plan-limit']]
196
+
197
+
198
+ class ModeOverrideIn(TypedDict):
199
+ mode: Literal['auto', 'capture', 'replay', 'off']
200
+ set_from: Literal['cli', 'devkit']
201
+
202
+
203
+ class ModeOverrideOut(TypedDict):
204
+ mode: Literal['auto', 'capture', 'replay', 'off']
205
+ set_from: Literal['cli', 'devkit']
206
+
207
+
208
+ class ModeOverrideState(TypedDict):
209
+ default_mode: Literal['auto', 'capture', 'replay', 'off']
210
+ environment_name: str
211
+ is_production: bool
212
+ mode: Optional[Literal['auto', 'capture', 'replay', 'off']]
213
+ set_at: Optional[str]
214
+ set_from: Optional[str]
215
+
216
+
217
+ class OnboardingWeekOut(TypedDict):
218
+ p50_seconds: Optional[int]
219
+ p90_seconds: Optional[int]
220
+ reached: int
221
+ signups: int
222
+ starts_on: str
223
+ within_five_minutes: int
224
+
225
+
226
+ class PinIn(TypedDict):
227
+ trace_id: str
228
+
229
+
230
+ class PinOut(TypedDict):
231
+ environment_id: str
232
+ set_at: str
233
+ set_from: str
234
+ trace_id: str
235
+
236
+
237
+ class PinState(TypedDict):
238
+ set_at: Optional[str]
239
+ set_from: Optional[str]
240
+ trace_id: Optional[str]
241
+
242
+
243
+ class ProjectOut(TypedDict):
244
+ environments: List[EnvironmentOut]
245
+ id: str
246
+ name: str
247
+ rules_version: int
248
+
249
+
250
+ class RulesIn(TypedDict):
251
+ ignore: List[str]
252
+ mask: List[str]
253
+ redact_fields: List[str]
254
+ redact_patterns: List[str]
255
+ rules_version: int
256
+
257
+
258
+ class RulesOut(TypedDict):
259
+ ignore: List[str]
260
+ mask: List[str]
261
+ redact_fields: List[str]
262
+ redact_patterns: List[str]
263
+ rules_version: int
264
+
265
+
266
+ class StartedPin(TypedDict):
267
+ captures: List[CaptureOut]
268
+ first_cache_key: str
269
+ set_at: str
270
+ set_from: str
271
+ trace_id: str
272
+
273
+
274
+ class TextPart(TypedDict):
275
+ text: str
276
+ type: NotRequired[Literal['text']]
277
+
278
+
279
+ class TokenCreated(TypedDict):
280
+ environment_id: Optional[str]
281
+ expires_at: Optional[str]
282
+ expires_soon: bool
283
+ id: str
284
+ kind: Literal['personal', 'service']
285
+ last_used_at: Optional[str]
286
+ name: str
287
+ never_expires: bool
288
+ prefix: str
289
+ revoked_at: Optional[str]
290
+ revoked_reason: Optional[str]
291
+ scope: Union[Literal['capture+replay', 'replay-only', 'read-only'], str]
292
+ token: str
293
+ user_id: Optional[str]
294
+
295
+
296
+ class TokenIn(TypedDict):
297
+ environment_id: NotRequired[Optional[str]]
298
+ expires_in_days: NotRequired[Optional[Union[int, str]]]
299
+ kind: Literal['personal', 'service']
300
+ name: str
301
+ scope: Literal['capture+replay', 'replay-only', 'read-only']
302
+
303
+
304
+ class TokenOut(TypedDict):
305
+ environment_id: Optional[str]
306
+ expires_at: Optional[str]
307
+ expires_soon: bool
308
+ id: str
309
+ kind: Literal['personal', 'service']
310
+ last_used_at: Optional[str]
311
+ name: str
312
+ never_expires: bool
313
+ prefix: str
314
+ revoked_at: Optional[str]
315
+ revoked_reason: Optional[str]
316
+ scope: Union[Literal['capture+replay', 'replay-only', 'read-only'], str]
317
+ user_id: Optional[str]
318
+
319
+
320
+ class TokenPolicy(TypedDict):
321
+ allow_non_expiring_tokens: bool
322
+
323
+
324
+ class TokenRenewed(TypedDict):
325
+ expires_at: str
326
+
327
+
328
+ class ToolCallPart(TypedDict):
329
+ arguments: NotRequired[Any]
330
+ id: NotRequired[Optional[str]]
331
+ name: str
332
+ type: NotRequired[Literal['tool_call']]
333
+
334
+
335
+ class ToolDef(TypedDict):
336
+ description: NotRequired[Optional[str]]
337
+ name: str
338
+ parameters: NotRequired[Any]
339
+
340
+
341
+ class TraceCallsOut(TypedDict):
342
+ calls: List[CallOut]
343
+ cost_micros: Optional[int]
344
+ cost_unknown_calls: int
345
+ duration_ms: Optional[int]
346
+ environment_id: str
347
+ id: str
348
+ input_tokens: Optional[int]
349
+ models: List[str]
350
+ output_tokens: Optional[int]
351
+ recorded_at: str
352
+
353
+
354
+ class TraceCursor(TypedDict):
355
+ before_at: str
356
+ before_id: str
357
+
358
+
359
+ class TraceStartIn(TypedDict):
360
+ cached: NotRequired[List[str]]
361
+ first_cache_key: str
362
+ group: NotRequired[Optional[str]]
363
+
364
+
365
+ class TraceSummaryOut(TypedDict):
366
+ calls: int
367
+ cost_micros: Optional[int]
368
+ cost_unknown_calls: int
369
+ duration_ms: Optional[int]
370
+ environment_id: str
371
+ id: str
372
+ input_tokens: Optional[int]
373
+ models: List[str]
374
+ output_tokens: Optional[int]
375
+ recorded_at: str
376
+
377
+
378
+ class ValidationError(TypedDict):
379
+ ctx: NotRequired[Dict[str, Any]]
380
+ input: NotRequired[Any]
381
+ loc: List[Union[str, int]]
382
+ msg: str
383
+ type: str
384
+
385
+
386
+ class VariationOut(TypedDict):
387
+ captures: List[CaptureOut]
388
+ recorded_at: str
389
+ trace_id: str
390
+
391
+
392
+ class WaitlistIn(TypedDict):
393
+ email: str
394
+
395
+
396
+ class WaitlistOut(TypedDict):
397
+ status: Literal['joined']
398
+
399
+
400
+ class WorkspaceOut(TypedDict):
401
+ allow_non_expiring_tokens: bool
402
+ event_retention_days: Optional[int]
403
+ id: str
404
+ name: str
405
+ role: str
406
+
407
+
408
+ class EventBatch(TypedDict):
409
+ events: List[EventIn]
410
+
411
+
412
+ class GroupDetailOut(TypedDict):
413
+ id: str
414
+ name: str
415
+ project_id: str
416
+ purpose: Optional[str]
417
+ trace_count: int
418
+ traces: List[GroupTraceOut]
419
+
420
+
421
+ class HTTPValidationError(TypedDict):
422
+ detail: NotRequired[List[ValidationError]]
423
+
424
+
425
+ class MeOut(TypedDict):
426
+ email: str
427
+ id: str
428
+ name: str
429
+ workspace: Optional[WorkspaceOut]
430
+
431
+
432
+ class Message(TypedDict):
433
+ parts: List[Union[TextPart, MediaPart, ToolCallPart]]
434
+ role: Literal['system', 'user', 'assistant', 'tool']
435
+ tool_call_id: NotRequired[Optional[str]]
436
+
437
+
438
+ class OnboardingReport(TypedDict):
439
+ weeks: List[OnboardingWeekOut]
440
+
441
+
442
+ class TraceListOut(TypedDict):
443
+ next: Optional[TraceCursor]
444
+ traces: List[TraceSummaryOut]
445
+
446
+
447
+ class TraceStartOut(TypedDict):
448
+ group_exists: Optional[bool]
449
+ mode: Literal['auto', 'capture', 'replay', 'off']
450
+ off_reason: Optional[Literal['production', 'plan-limit']]
451
+ pin: Optional[StartedPin]
452
+ rules_version: int
453
+ traces: List[VariationOut]
454
+ urls_expire_at: str
455
+
456
+
457
+ class CallContentOut(TypedDict):
458
+ ended: NotRequired[Optional[Literal['complete', 'aborted', 'error']]]
459
+ error_status: NotRequired[Optional[int]]
460
+ error_text: NotRequired[Optional[str]]
461
+ format: Literal['openai-chat', 'openai-responses', 'anthropic-messages', 'raw']
462
+ input: NotRequired[List[Message]]
463
+ output: NotRequired[List[Message]]
464
+ request: NotRequired[Any]
465
+ response: NotRequired[Any]
466
+ tools: NotRequired[List[ToolDef]]
@@ -0,0 +1,149 @@
1
+ """Work the SDK does off the call's path: uploads and event flushes.
2
+
3
+ One daemon worker thread runs the uploads and event flushes in turn (Q2). A trace start has a
4
+ thread of its own, like a download, because a call waits for it and must not queue behind an
5
+ upload; it is left out of the exit wait. A hung server never keeps the app from exiting; `atexit`
6
+ gives the queued work one two-second deadline.
7
+ """
8
+
9
+ import atexit
10
+ import queue
11
+ import threading
12
+ import time
13
+ from collections.abc import Callable
14
+ from concurrent.futures import Future
15
+ from typing import Any
16
+
17
+ EXIT_GRACE_S = 2.0
18
+
19
+ _jobs: queue.SimpleQueue[tuple[Future, Callable[[], Any]] | None] = queue.SimpleQueue()
20
+ _idle = threading.Condition()
21
+ _active = 0
22
+ _timers: dict[object, tuple[float, Callable[[], Any]]] = {}
23
+ _exit_flushes: list[Callable[[], None]] = []
24
+ _worker: threading.Thread | None = None
25
+ _exiting = False
26
+
27
+
28
+ def run(job: Callable[[], Any]) -> Future:
29
+ global _active
30
+ future: Future = Future()
31
+ with _idle:
32
+ _start_worker()
33
+ _active += 1
34
+ _jobs.put((future, job))
35
+ return future
36
+
37
+
38
+ def run_apart(job: Callable[[], Any]) -> Future:
39
+ """Runs `job` on a daemon thread of its own, outside the exit wait: the call that needs its
40
+ result gives up on it itself."""
41
+ future: Future = Future()
42
+ threading.Thread(
43
+ target=_settle, args=(future, job), name="agentdevlabs-start", daemon=True
44
+ ).start()
45
+ return future
46
+
47
+
48
+ def after(delay_s: float, key: object, job: Callable[[], Any]) -> None:
49
+ """Runs `job` once `delay_s` has passed, unless `after` or `cancel` is called again for `key`
50
+ first. Once the process is exiting there is no time to wait, so `job` runs at once and the exit
51
+ wait covers it."""
52
+ with _idle:
53
+ if _exiting:
54
+ cancel(key)
55
+ run(job)
56
+ return
57
+ _start_worker()
58
+ _timers[key] = (time.monotonic() + delay_s, job)
59
+ _jobs.put(None)
60
+
61
+
62
+ def cancel(key: object) -> None:
63
+ with _idle:
64
+ _timers.pop(key, None)
65
+
66
+
67
+ def before_exit(flush: Callable[[], None]) -> None:
68
+ """Registers a callback that queues its pending work when the process exits, ahead of the
69
+ single wait."""
70
+ with _idle:
71
+ _exit_flushes.append(flush)
72
+
73
+
74
+ def wait_idle(timeout_s: float | None) -> None:
75
+ with _idle:
76
+ _idle.wait_for(lambda: _active == 0, timeout=timeout_s)
77
+
78
+
79
+ def _start_worker() -> None:
80
+ global _worker
81
+ if _worker is None:
82
+ atexit.register(_at_exit)
83
+ _worker = threading.Thread(target=_work, name="agentdevlabs", daemon=True)
84
+ _worker.start()
85
+
86
+
87
+ def _at_exit() -> None:
88
+ global _exiting
89
+ with _idle:
90
+ _exiting = True
91
+ flushes = list(_exit_flushes)
92
+ for flush in flushes:
93
+ flush()
94
+ wait_idle(EXIT_GRACE_S)
95
+
96
+
97
+ def _work() -> None:
98
+ while True:
99
+ item = _take()
100
+ if item is not None:
101
+ _run_one(*item)
102
+
103
+
104
+ def _take() -> tuple[Future, Callable[[], Any]] | None:
105
+ """The next job: a timer's once it is due, else a queued one (None when woken to re-check
106
+ the timers)."""
107
+ due = _due_timer()
108
+ if due is not None:
109
+ return due
110
+ try:
111
+ return _jobs.get(timeout=_next_timer_wait())
112
+ except queue.Empty:
113
+ return None
114
+
115
+
116
+ def _next_timer_wait() -> float | None:
117
+ with _idle:
118
+ if not _timers:
119
+ return None
120
+ return max(0.0, min(due for due, _ in _timers.values()) - time.monotonic())
121
+
122
+
123
+ def _due_timer() -> tuple[Future, Callable[[], Any]] | None:
124
+ global _active
125
+ with _idle:
126
+ now = time.monotonic()
127
+ for key, (due, job) in _timers.items():
128
+ if due <= now:
129
+ del _timers[key]
130
+ _active += 1
131
+ return Future(), job
132
+ return None
133
+
134
+
135
+ def _settle(future: Future, job: Callable[[], Any]) -> None:
136
+ try:
137
+ future.set_result(job())
138
+ except BaseException as error:
139
+ future.set_exception(error)
140
+
141
+
142
+ def _run_one(future: Future, job: Callable[[], Any]) -> None:
143
+ global _active
144
+ try:
145
+ _settle(future, job)
146
+ finally:
147
+ with _idle:
148
+ _active -= 1
149
+ _idle.notify_all()