xiii-cli-core 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 @@
1
+ """The product-neutral CLI core: an entrypoint hands it a `config.Product`."""
@@ -0,0 +1,568 @@
1
+ import json as json_module
2
+ import os
3
+ import random
4
+ import re
5
+ import tempfile
6
+ import time
7
+ from collections.abc import Iterable, Iterator, Mapping
8
+ from contextlib import ExitStack, contextmanager, suppress
9
+ from dataclasses import dataclass
10
+ from datetime import UTC, datetime
11
+ from email.message import Message
12
+ from email.utils import parsedate_to_datetime
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ import httpx
17
+
18
+ from xiii_cli_core.config import ProductConfig
19
+ from xiii_cli_core.errors import (
20
+ ApiError,
21
+ AuthenticationError,
22
+ AuthorizationError,
23
+ CliError,
24
+ NetworkError,
25
+ RateLimitError,
26
+ ThreadProtocolError,
27
+ )
28
+ from xiii_cli_core.thread import parse_sse
29
+
30
+ MAX_BUFFERED_RESPONSE_BYTES = 10 * 1024 * 1024
31
+ MAX_ERROR_RESPONSE_BYTES = 64 * 1024
32
+ # The server answers a refusal with `{"detail": "MAIL_ACCOUNT_NOT_FOUND"}`.
33
+ ERROR_CODE = re.compile(r"[A-Z][A-Z0-9_]*")
34
+ # Retries after the first attempt. A GET or HEAD is retried on a dropped
35
+ # connection or a transient 5xx; any method on a 429, which the rate limiter
36
+ # answers before the route runs. Nothing else is retried, so a POST that may
37
+ # have reached the server is never sent twice.
38
+ MAX_RETRIES = 3
39
+ RETRY_BASE_SECONDS = 0.5
40
+ RETRY_MAX_SECONDS = 8.0
41
+ # A server asking for a longer pause than this is reported, not waited out.
42
+ MAX_RETRY_AFTER_SECONDS = 60.0
43
+ IDEMPOTENT_METHODS = frozenset({"GET", "HEAD"})
44
+ TRANSIENT_SERVER_STATUSES = frozenset({500, 502, 503, 504})
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class ApiResult:
49
+ status_code: int
50
+ content_type: str
51
+ content: bytes
52
+ headers: Mapping[str, str]
53
+
54
+ def payload(self) -> Any:
55
+ if not self.content:
56
+ return None
57
+ if self.content_type == "application/json" or self.content_type.endswith(
58
+ "+json"
59
+ ):
60
+ try:
61
+ return json_module.loads(self.content)
62
+ except ValueError as exc:
63
+ raise CliError("API returned invalid JSON") from exc
64
+ if self.content_type.startswith("text/"):
65
+ return self.content.decode("utf-8", errors="replace")
66
+ return self.content
67
+
68
+ @property
69
+ def is_binary(self) -> bool:
70
+ return is_binary_content_type(self.content_type)
71
+
72
+ @property
73
+ def filename(self) -> str | None:
74
+ return _response_filename(self.headers)
75
+
76
+
77
+ @dataclass(frozen=True)
78
+ class ApiDownloadResult:
79
+ status_code: int
80
+ content_type: str
81
+ headers: Mapping[str, str]
82
+ bytes_written: int
83
+ output: Path
84
+
85
+ @property
86
+ def filename(self) -> str | None:
87
+ return _response_filename(self.headers)
88
+
89
+
90
+ class ApiClient:
91
+ def __init__(
92
+ self,
93
+ config: ProductConfig,
94
+ token: str,
95
+ *,
96
+ transport: httpx.BaseTransport | None = None,
97
+ ):
98
+ self._client = httpx.Client(
99
+ base_url=config.base_url,
100
+ headers={
101
+ "Authorization": f"Bearer {token}",
102
+ "Accept": "application/json",
103
+ "User-Agent": config.user_agent,
104
+ },
105
+ timeout=httpx.Timeout(config.timeout, connect=min(5.0, config.timeout)),
106
+ transport=transport,
107
+ )
108
+
109
+ def __enter__(self):
110
+ self._client.__enter__()
111
+ return self
112
+
113
+ def __exit__(self, exc_type, exc, traceback) -> None:
114
+ self._client.__exit__(exc_type, exc, traceback)
115
+
116
+ def request(
117
+ self,
118
+ method: str,
119
+ path: str,
120
+ *,
121
+ params: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
122
+ json: Any = None,
123
+ data: Mapping[str, Any] | None = None,
124
+ files: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
125
+ headers: Mapping[str, str] | None = None,
126
+ content: bytes | Iterable[bytes] | None = None,
127
+ redact_values: Iterable[str] = (),
128
+ ) -> Any:
129
+ return self.request_result(
130
+ method,
131
+ path,
132
+ params=params,
133
+ json=json,
134
+ data=data,
135
+ files=files,
136
+ headers=headers,
137
+ content=content,
138
+ redact_values=redact_values,
139
+ ).payload()
140
+
141
+ def request_result(
142
+ self,
143
+ method: str,
144
+ path: str,
145
+ *,
146
+ params: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
147
+ json: Any = None,
148
+ data: Mapping[str, Any] | None = None,
149
+ files: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
150
+ headers: Mapping[str, str] | None = None,
151
+ content: bytes | Iterable[bytes] | None = None,
152
+ redact_values: Iterable[str] = (),
153
+ ) -> ApiResult:
154
+ try:
155
+ with self._send(
156
+ method,
157
+ path,
158
+ params=params,
159
+ json=json,
160
+ data=data,
161
+ files=files,
162
+ headers=headers,
163
+ content=content,
164
+ redact_values=redact_values,
165
+ ) as response:
166
+ content_type = _content_type(response)
167
+ response_headers = dict(response.headers)
168
+ if is_binary_content_type(content_type):
169
+ return ApiResult(
170
+ status_code=response.status_code,
171
+ content_type=content_type,
172
+ content=b"",
173
+ headers=response_headers,
174
+ )
175
+ buffered = bytearray()
176
+ for chunk in response.iter_bytes():
177
+ buffered.extend(chunk)
178
+ if len(buffered) > MAX_BUFFERED_RESPONSE_BYTES:
179
+ raise CliError(
180
+ "API response exceeds the in-memory output limit; "
181
+ "use --output to stream it to a file"
182
+ )
183
+ return ApiResult(
184
+ status_code=response.status_code,
185
+ content_type=content_type,
186
+ content=bytes(buffered),
187
+ headers=response_headers,
188
+ )
189
+ except httpx.RequestError as exc:
190
+ raise NetworkError(f"Request failed: {exc}") from exc
191
+
192
+ def request_to_file(
193
+ self,
194
+ method: str,
195
+ path: str,
196
+ output: Path,
197
+ *,
198
+ overwrite: bool = False,
199
+ params: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
200
+ json: Any = None,
201
+ data: Mapping[str, Any] | None = None,
202
+ files: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
203
+ headers: Mapping[str, str] | None = None,
204
+ content: bytes | Iterable[bytes] | None = None,
205
+ redact_values: Iterable[str] = (),
206
+ ) -> ApiDownloadResult:
207
+ temporary: Path | None = None
208
+ try:
209
+ with self._send(
210
+ method,
211
+ path,
212
+ params=params,
213
+ json=json,
214
+ data=data,
215
+ files=files,
216
+ headers=headers,
217
+ content=content,
218
+ redact_values=redact_values,
219
+ ) as response:
220
+ descriptor, temporary_name = tempfile.mkstemp(
221
+ prefix=f".{output.name}.",
222
+ suffix=".part",
223
+ dir=output.parent,
224
+ )
225
+ temporary = Path(temporary_name)
226
+ bytes_written = 0
227
+ with os.fdopen(descriptor, "wb") as target:
228
+ for chunk in response.iter_bytes():
229
+ target.write(chunk)
230
+ bytes_written += len(chunk)
231
+ target.flush()
232
+ os.fsync(target.fileno())
233
+ if overwrite:
234
+ os.replace(temporary, output)
235
+ else:
236
+ os.link(temporary, output)
237
+ temporary.unlink()
238
+ temporary = None
239
+ return ApiDownloadResult(
240
+ status_code=response.status_code,
241
+ content_type=_content_type(response),
242
+ headers=dict(response.headers),
243
+ bytes_written=bytes_written,
244
+ output=output,
245
+ )
246
+ except FileExistsError as exc:
247
+ raise CliError(
248
+ f"Output file already exists: {output}; pass --overwrite to replace it"
249
+ ) from exc
250
+ except httpx.RequestError as exc:
251
+ raise NetworkError(f"Request failed: {exc}") from exc
252
+ except OSError as exc:
253
+ raise CliError(f"Could not write output file {output}: {exc}") from exc
254
+ finally:
255
+ if temporary is not None:
256
+ with suppress(OSError):
257
+ temporary.unlink(missing_ok=True)
258
+
259
+ def current_api_key(self) -> dict[str, Any]:
260
+ result = self.request("GET", "/me/api-keys/current")
261
+ if not isinstance(result, dict):
262
+ raise CliError("Unexpected API key status response")
263
+ return result
264
+
265
+ def list_workspaces(self) -> list[dict[str, Any]]:
266
+ """Workspaces the token's user belongs to, used to name the local slot."""
267
+ result = self.request("GET", "/workspace")
268
+ if not isinstance(result, list):
269
+ raise CliError("Unexpected workspace list response")
270
+ return [entry for entry in result if isinstance(entry, dict)]
271
+
272
+ def stream_thread(
273
+ self, payload: Mapping[str, Any], *, test_run_id: str
274
+ ) -> Iterator[dict[str, Any]]:
275
+ yield from self._stream_sse(
276
+ "/threads/chat",
277
+ payload,
278
+ headers={"X-Test-Run-ID": test_run_id},
279
+ )
280
+
281
+ def stream_agent(self, payload: Mapping[str, Any]) -> Iterator[dict[str, Any]]:
282
+ """Start a customer-facing agent turn without test-only headers."""
283
+ yield from self._stream_sse("/threads/chat", payload)
284
+
285
+ def resume_agent(
286
+ self, thread_id: str, payload: Mapping[str, Any]
287
+ ) -> Iterator[dict[str, Any]]:
288
+ """Resume one interrupted turn with explicit human decisions."""
289
+ yield from self._stream_sse(f"/threads/{thread_id}/resume", payload)
290
+
291
+ def _stream_sse(
292
+ self,
293
+ path: str,
294
+ payload: Mapping[str, Any],
295
+ *,
296
+ headers: Mapping[str, str] | None = None,
297
+ ) -> Iterator[dict[str, Any]]:
298
+ stream_headers = {"Accept": "text/event-stream", **(headers or {})}
299
+ try:
300
+ with self._send(
301
+ "POST",
302
+ path,
303
+ json=payload,
304
+ headers=stream_headers,
305
+ timeout=httpx.Timeout(300.0, connect=5.0),
306
+ ) as response:
307
+ content_type = response.headers.get("content-type", "")
308
+ if content_type.split(";", 1)[0].strip().lower() != "text/event-stream":
309
+ raise ThreadProtocolError(
310
+ f"Expected text/event-stream, received {content_type or 'no content type'}"
311
+ )
312
+ yield from parse_sse(response.iter_lines())
313
+ except httpx.RequestError as exc:
314
+ raise NetworkError(f"Request failed: {exc}") from exc
315
+
316
+ @contextmanager
317
+ def _send(
318
+ self,
319
+ method: str,
320
+ path: str,
321
+ *,
322
+ files: Mapping[str, Any] | list[tuple[str, Any]] | None = None,
323
+ content: bytes | Iterable[bytes] | None = None,
324
+ redact_values: Iterable[str] = (),
325
+ **arguments: Any,
326
+ ) -> Iterator[httpx.Response]:
327
+ """Open a successful response, retrying what is safe to send again.
328
+
329
+ A streamed `content` body cannot be replayed, so it is sent once.
330
+ """
331
+ replayable = (content is None or isinstance(content, bytes)) and _rewindable(
332
+ files
333
+ )
334
+ attempt = 0
335
+ while True:
336
+ _rewind(files)
337
+ with ExitStack() as stack:
338
+ try:
339
+ response = stack.enter_context(
340
+ self._client.stream(
341
+ method, path, files=files, content=content, **arguments
342
+ )
343
+ )
344
+ except httpx.TransportError:
345
+ if not (
346
+ replayable
347
+ and method in IDEMPOTENT_METHODS
348
+ and attempt < MAX_RETRIES
349
+ ):
350
+ raise
351
+ _pause(_backoff(attempt))
352
+ attempt += 1
353
+ continue
354
+ delay = _retry_delay(method, response, attempt) if replayable else None
355
+ if delay is not None:
356
+ stack.close()
357
+ _pause(delay)
358
+ attempt += 1
359
+ continue
360
+ if response.is_error:
361
+ _raise_for_response(response, redact_values=redact_values)
362
+ yield response
363
+ return
364
+
365
+ def thread_interactions(self, thread_id: str) -> dict[str, Any]:
366
+ result = self.request("GET", f"/threads/{thread_id}/interactions")
367
+ if not isinstance(result, dict):
368
+ raise CliError("Unexpected thread interactions response")
369
+ return result
370
+
371
+
372
+ def _rewindable(files: Mapping[str, Any] | list[tuple[str, Any]] | None) -> bool:
373
+ return all(
374
+ _file_handle(entry) is None or _file_handle(entry).seekable()
375
+ for entry in _file_entries(files)
376
+ )
377
+
378
+
379
+ def _rewind(files: Mapping[str, Any] | list[tuple[str, Any]] | None) -> None:
380
+ for entry in _file_entries(files):
381
+ handle = _file_handle(entry)
382
+ if handle is not None:
383
+ handle.seek(0)
384
+
385
+
386
+ def _file_entries(files: Mapping[str, Any] | list[tuple[str, Any]] | None) -> list:
387
+ if files is None:
388
+ return []
389
+ return list(
390
+ files.values() if isinstance(files, Mapping) else (v for _k, v in files)
391
+ )
392
+
393
+
394
+ def _file_handle(entry: Any) -> Any:
395
+ handle = entry[1] if isinstance(entry, tuple) else entry
396
+ return handle if hasattr(handle, "seek") and hasattr(handle, "seekable") else None
397
+
398
+
399
+ def _pause(seconds: float) -> None:
400
+ time.sleep(seconds)
401
+
402
+
403
+ def _backoff(attempt: int) -> float:
404
+ """Full jitter: a random pause up to the doubled base, capped."""
405
+ return random.uniform(0, min(RETRY_MAX_SECONDS, RETRY_BASE_SECONDS * 2**attempt))
406
+
407
+
408
+ def _retry_delay(method: str, response: httpx.Response, attempt: int) -> float | None:
409
+ status = response.status_code
410
+ transient = status in TRANSIENT_SERVER_STATUSES and method in IDEMPOTENT_METHODS
411
+ if attempt >= MAX_RETRIES or not (status == 429 or transient):
412
+ return None
413
+ retry_after = _retry_after_seconds(response.headers)
414
+ if retry_after is None:
415
+ return _backoff(attempt)
416
+ return retry_after if retry_after <= MAX_RETRY_AFTER_SECONDS else None
417
+
418
+
419
+ def _retry_after_seconds(headers: Mapping[str, str]) -> float | None:
420
+ """`Retry-After` as seconds: delay-seconds or an HTTP-date (RFC 9110 10.2.3)."""
421
+ value = headers.get("retry-after", "").strip()
422
+ if not value:
423
+ return None
424
+ if value.isdigit():
425
+ return float(value)
426
+ try:
427
+ moment = parsedate_to_datetime(value)
428
+ except (TypeError, ValueError):
429
+ return None
430
+ if moment.tzinfo is None:
431
+ moment = moment.replace(tzinfo=UTC)
432
+ return max(0.0, (moment - datetime.now(UTC)).total_seconds())
433
+
434
+
435
+ def _response_detail(
436
+ content: bytes,
437
+ *,
438
+ truncated: bool,
439
+ redact_values: Iterable[str],
440
+ ) -> tuple[str | None, Any]:
441
+ """The server's error code and its redacted `detail`, kept as JSON.
442
+
443
+ A body that is not JSON, or was cut at the error-size limit, stays text.
444
+ """
445
+ try:
446
+ payload = json_module.loads(content)
447
+ except (UnicodeDecodeError, ValueError):
448
+ rendered = _redact_text(
449
+ content.decode("utf-8", errors="replace"), redact_values
450
+ )
451
+ return None, f"{rendered}…" if truncated else rendered or None
452
+ detail = payload.get("detail") if isinstance(payload, dict) else payload
453
+ detail = _redact_strings(_redact_error_inputs(detail), redact_values)
454
+ code = detail if isinstance(detail, str) and ERROR_CODE.fullmatch(detail) else None
455
+ return code, detail
456
+
457
+
458
+ def _redact_strings(value: Any, redact_values: Iterable[str]) -> Any:
459
+ candidates = list(redact_values)
460
+ if isinstance(value, str):
461
+ return _redact_text(value, candidates)
462
+ if isinstance(value, list):
463
+ return [_redact_strings(item, candidates) for item in value]
464
+ if isinstance(value, dict):
465
+ # Keys too: a validation error can echo a submitted value as a key.
466
+ return {
467
+ _redact_text(str(key), candidates): _redact_strings(item, candidates)
468
+ for key, item in value.items()
469
+ }
470
+ return value
471
+
472
+
473
+ def _summary(detail: Any) -> str | None:
474
+ if detail is None or isinstance(detail, str):
475
+ return detail or None
476
+ return json_module.dumps(detail, ensure_ascii=False, default=str)
477
+
478
+
479
+ def _redact_error_inputs(value: Any) -> Any:
480
+ if isinstance(value, list):
481
+ return [_redact_error_inputs(item) for item in value]
482
+ if isinstance(value, dict):
483
+ return {
484
+ key: (
485
+ "<redacted>"
486
+ if str(key).lower() == "input"
487
+ else _redact_error_inputs(item)
488
+ )
489
+ for key, item in value.items()
490
+ }
491
+ return value
492
+
493
+
494
+ def _redact_text(value: str, redact_values: Iterable[str]) -> str:
495
+ rendered = value
496
+ candidates = sorted(
497
+ {candidate for candidate in redact_values if candidate},
498
+ key=len,
499
+ reverse=True,
500
+ )
501
+ for candidate in candidates:
502
+ rendered = rendered.replace(candidate, "<redacted>")
503
+ return rendered
504
+
505
+
506
+ def _read_error_content(response: httpx.Response) -> tuple[bytes, bool]:
507
+ content = bytearray()
508
+ for chunk in response.iter_bytes():
509
+ remaining = MAX_ERROR_RESPONSE_BYTES + 1 - len(content)
510
+ content.extend(chunk[:remaining])
511
+ if len(content) > MAX_ERROR_RESPONSE_BYTES:
512
+ return bytes(content[:MAX_ERROR_RESPONSE_BYTES]), True
513
+ return bytes(content), False
514
+
515
+
516
+ def _raise_for_response(
517
+ response: httpx.Response, *, redact_values: Iterable[str] = ()
518
+ ) -> None:
519
+ content, truncated = _read_error_content(response)
520
+ code, detail = _response_detail(
521
+ content,
522
+ truncated=truncated,
523
+ redact_values=redact_values,
524
+ )
525
+ summary = f"{response.status_code}: {_summary(detail) or response.reason_phrase}"
526
+ error_fields: dict[str, Any] = {
527
+ "status_code": response.status_code,
528
+ "code": code,
529
+ "detail": detail,
530
+ }
531
+ if response.status_code == 401:
532
+ raise AuthenticationError(
533
+ f"API rejected authentication ({summary})", **error_fields
534
+ )
535
+ if response.status_code == 403:
536
+ raise AuthorizationError(
537
+ f"API denied this operation ({summary})", **error_fields
538
+ )
539
+ if response.status_code == 429:
540
+ raise RateLimitError(
541
+ f"API rate limit reached ({summary})",
542
+ retry_after=_retry_after_seconds(response.headers),
543
+ **error_fields,
544
+ )
545
+ if response.is_error:
546
+ raise ApiError(f"API request failed ({summary})", **error_fields)
547
+
548
+
549
+ def _content_type(response: httpx.Response) -> str:
550
+ return response.headers.get("content-type", "").split(";", 1)[0].strip().lower()
551
+
552
+
553
+ def is_binary_content_type(content_type: str) -> bool:
554
+ return bool(content_type) and not (
555
+ content_type == "application/json"
556
+ or content_type.endswith("+json")
557
+ or content_type.startswith("text/")
558
+ )
559
+
560
+
561
+ def _response_filename(headers: Mapping[str, str]) -> str | None:
562
+ disposition = headers.get("content-disposition")
563
+ if not disposition:
564
+ return None
565
+ message = Message()
566
+ message["content-disposition"] = disposition
567
+ filename = message.get_filename()
568
+ return Path(filename).name if filename else None