cloakapi 0.5.1__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.
Files changed (61) hide show
  1. LICENSE +202 -0
  2. NOTICE +18 -0
  3. THIRD-PARTY-NOTICES.md +22 -0
  4. TRADEMARKS.md +19 -0
  5. cloakapi/__init__.py +271 -0
  6. cloakapi/_disclosure/clk.txt +11 -0
  7. cloakapi/_disclosure/clk_message.txt +11 -0
  8. cloakapi/_disclosure/cloak_angle.txt +16 -0
  9. cloakapi/_disclosure/cloak_angle_message.txt +16 -0
  10. cloakapi/_http.py +443 -0
  11. cloakapi/_pretokenised.py +134 -0
  12. cloakapi/_relay.py +213 -0
  13. cloakapi/_release.py +30 -0
  14. cloakapi/_request_strings.py +1267 -0
  15. cloakapi/_ruleset/patterns.json +2238 -0
  16. cloakapi/_stream_detok.py +788 -0
  17. cloakapi/_version.py +31 -0
  18. cloakapi/async_client.py +704 -0
  19. cloakapi/attachments.py +176 -0
  20. cloakapi/cli.py +245 -0
  21. cloakapi/client.py +848 -0
  22. cloakapi/config.py +491 -0
  23. cloakapi/coverage.py +21 -0
  24. cloakapi/degraded.py +196 -0
  25. cloakapi/disclosure.py +334 -0
  26. cloakapi/engine.py +922 -0
  27. cloakapi/errors.py +304 -0
  28. cloakapi/notices.py +142 -0
  29. cloakapi/pii/__init__.py +4 -0
  30. cloakapi/pii/_checksum.py +510 -0
  31. cloakapi/pii/_ruleset.py +131 -0
  32. cloakapi/pii/patterns.py +1713 -0
  33. cloakapi/pii/rulefile.py +738 -0
  34. cloakapi/pii/tokenizer.py +537 -0
  35. cloakapi/posture.py +112 -0
  36. cloakapi/py.typed +1 -0
  37. cloakapi/receipts.py +605 -0
  38. cloakapi/resources/__init__.py +32 -0
  39. cloakapi/resources/admin.py +104 -0
  40. cloakapi/resources/buffer.py +54 -0
  41. cloakapi/resources/chat.py +293 -0
  42. cloakapi/resources/detect.py +115 -0
  43. cloakapi/resources/messages.py +260 -0
  44. cloakapi/resources/models.py +58 -0
  45. cloakapi/resources/receipts.py +252 -0
  46. cloakapi/resources/reconstruct.py +173 -0
  47. cloakapi/resources/tokens.py +47 -0
  48. cloakapi/review.py +112 -0
  49. cloakapi/streaming.py +446 -0
  50. cloakapi/surrogate_mode.py +308 -0
  51. cloakapi/types.py +284 -0
  52. cloakapi-0.5.1.dist-info/METADATA +441 -0
  53. cloakapi-0.5.1.dist-info/RECORD +61 -0
  54. cloakapi-0.5.1.dist-info/WHEEL +4 -0
  55. cloakapi-0.5.1.dist-info/entry_points.txt +2 -0
  56. cloakapi-0.5.1.dist-info/licenses/LICENSE +202 -0
  57. cloakapi-0.5.1.dist-info/licenses/NOTICE +18 -0
  58. licenses/Apache-2.0.txt +202 -0
  59. licenses/CC-BY-4.0.txt +104 -0
  60. licenses/MIT-Faker.txt +21 -0
  61. licenses/MIT.txt +21 -0
@@ -0,0 +1,173 @@
1
+ """Reconstruct resource — LEVEL-1, FULLY CLIENT-SIDE (local de-tokenisation).
2
+
3
+ LEVEL-1 INVARIANT (mirrors the TS SDK + browser-portal): raw PII NEVER egresses
4
+ to the gateway. The gateway is a blind relay and does not detokenise or
5
+ reconstruct; POST /v1/reconstruct is a RETIRED endpoint. Reconstruction therefore
6
+ happens ENTIRELY ON THIS MACHINE:
7
+
8
+ 1. Detokenise ``response_text`` locally using the caller's alias map (which
9
+ holds the REAL originals) — a plain, longest-placeholder-first substitution
10
+ that never leaves this process.
11
+ 2. Serialise the plaintext into the requested TEXT/STRUCTURED format
12
+ (txt/md/html/csv/json/yaml/xml) using only the Python standard library.
13
+
14
+ CAPABILITY NARROWED (2026-07-13): the Python SDK has no ``@cloakapi/reconstruction``
15
+ engine, so it does NOT rebuild BINARY office formats (docx/pdf/xlsx/pptx/…).
16
+ Requesting one raises :class:`ReconstructionNotSupportedError` — it is FAIL-CLOSED,
17
+ never relayed to the gateway. This is a deliberate narrowing from the old
18
+ server-side rebuild: it removed the only path where the alias map (real PII) left
19
+ the client. For binary formats, use the TypeScript SDK / desktop app (which bundle
20
+ the client-side engine), or detokenise the text here and build the file yourself.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import html as _html
26
+ import json as _json
27
+ from dataclasses import dataclass, field
28
+ from typing import TYPE_CHECKING, Any
29
+
30
+ if TYPE_CHECKING:
31
+ from ..async_client import AsyncCloakAPI
32
+ from ..client import CloakAPI
33
+
34
+
35
+ class ReconstructionNotSupportedError(ValueError):
36
+ """Raised (fail-closed) when a BINARY/office format is requested.
37
+
38
+ The Python SDK reconstructs only text/structured formats on-device. It never
39
+ falls back to a gateway round-trip, so no alias map / PII ever egresses.
40
+ """
41
+
42
+
43
+ # Text/structured formats the Python SDK can build with the standard library.
44
+ _TEXT_FORMATS = {"txt", "md", "markdown", "html", "csv", "json", "yaml", "yml", "xml"}
45
+
46
+ _MIME = {
47
+ "txt": "text/plain",
48
+ "md": "text/markdown",
49
+ "markdown": "text/markdown",
50
+ "html": "text/html",
51
+ "csv": "text/csv",
52
+ "json": "application/json",
53
+ "yaml": "text/yaml",
54
+ "yml": "text/yaml",
55
+ "xml": "application/xml",
56
+ }
57
+
58
+ _EXT = {"markdown": "md", "yml": "yaml"}
59
+
60
+
61
+ @dataclass
62
+ class ReconstructResult:
63
+ """A reconstructed file, built fully on-device."""
64
+
65
+ content: bytes
66
+ content_type: str
67
+ filename: str | None
68
+ # Always empty: reconstruction is local, so there is no gateway round-trip
69
+ # and therefore no server receipt headers. Kept for result-shape stability.
70
+ receipt_headers: dict[str, str] = field(default_factory=dict)
71
+
72
+
73
+ def _alias_map_to_pairs(alias_map: dict[str, Any]) -> list[tuple[str, str]]:
74
+ """Normalise the alias map to ``[(placeholder, original), …]``.
75
+
76
+ Accepts either the structured shape ``{"entries": [{"placeholder", "original"}]}``
77
+ or a flat ``{token: original}`` record.
78
+ """
79
+ if not isinstance(alias_map, dict):
80
+ return []
81
+ entries = alias_map.get("entries")
82
+ if isinstance(entries, list):
83
+ pairs: list[tuple[str, str]] = []
84
+ for e in entries:
85
+ if isinstance(e, dict) and isinstance(e.get("placeholder"), str) and isinstance(
86
+ e.get("original"), str
87
+ ):
88
+ pairs.append((e["placeholder"], e["original"]))
89
+ return pairs
90
+ return [(k, v) for k, v in alias_map.items() if isinstance(k, str) and isinstance(v, str)]
91
+
92
+
93
+ def _detokenise_local(text: str, pairs: list[tuple[str, str]]) -> str:
94
+ """On-device restore: longest key, no rescan of the inserted original."""
95
+ from ..pii.tokenizer import detokenize
96
+
97
+ mapping: dict[str, str] = {}
98
+ for placeholder, original in pairs:
99
+ if placeholder and placeholder not in mapping:
100
+ mapping[placeholder] = original
101
+ return detokenize(text, mapping)
102
+
103
+
104
+ def _build_text_format(plaintext: str, fmt: str) -> str:
105
+ if fmt == "json":
106
+ try:
107
+ return _json.dumps(_json.loads(plaintext), indent=2, ensure_ascii=False)
108
+ except (ValueError, TypeError):
109
+ return _json.dumps({"content": plaintext}, indent=2, ensure_ascii=False)
110
+ if fmt == "html":
111
+ return (
112
+ '<!doctype html>\n<html>\n<head><meta charset="utf-8"></head>\n<body>\n<pre>'
113
+ + _html.escape(plaintext)
114
+ + "</pre>\n</body>\n</html>\n"
115
+ )
116
+ # txt / md / markdown / csv / yaml / yml / xml — the detokenised text IS the content.
117
+ return plaintext
118
+
119
+
120
+ def _reconstruct_local(response_text: str, alias_map: dict[str, Any], target_format: str) -> ReconstructResult:
121
+ fmt = str(target_format or "txt").lower()
122
+ if fmt not in _TEXT_FORMATS:
123
+ raise ReconstructionNotSupportedError(
124
+ f"reconstruct: '{fmt}' is a binary/office format the Python SDK does not build. "
125
+ "Reconstruction is FULLY LOCAL — the alias map is never sent to the gateway. Use a "
126
+ "text format (txt/md/html/csv/json/yaml/xml), or the TypeScript SDK / desktop app "
127
+ "(which bundle the client-side @cloakapi/reconstruction engine) for office formats."
128
+ )
129
+ pairs = _alias_map_to_pairs(alias_map)
130
+ # Detokenise on THIS machine — real PII substituted locally.
131
+ plaintext = _detokenise_local(str(response_text or ""), pairs)
132
+ content = _build_text_format(plaintext, fmt).encode("utf-8")
133
+ ext = _EXT.get(fmt, fmt)
134
+ return ReconstructResult(
135
+ content=content,
136
+ content_type=_MIME.get(fmt, "text/plain"),
137
+ filename=f"reconstructed.{ext}",
138
+ receipt_headers={},
139
+ )
140
+
141
+
142
+ class ReconstructResource:
143
+ def __init__(self, client: CloakAPI) -> None:
144
+ self._client = client
145
+
146
+ def create(
147
+ self,
148
+ *,
149
+ response_text: str,
150
+ alias_map: dict[str, Any],
151
+ target_format: str,
152
+ ) -> ReconstructResult:
153
+ """Reconstruct ``response_text`` into ``target_format`` FULLY ON-DEVICE.
154
+
155
+ The alias map is applied locally (detokenisation); nothing is sent to the
156
+ gateway. Text/structured formats only — binary/office formats fail-closed
157
+ (see :class:`ReconstructionNotSupportedError`)."""
158
+ return _reconstruct_local(response_text, alias_map, target_format)
159
+
160
+
161
+ class AsyncReconstructResource:
162
+ def __init__(self, client: AsyncCloakAPI) -> None:
163
+ self._client = client
164
+
165
+ async def create(
166
+ self,
167
+ *,
168
+ response_text: str,
169
+ alias_map: dict[str, Any],
170
+ target_format: str,
171
+ ) -> ReconstructResult:
172
+ """Async wrapper around the local reconstruction (no I/O — CPU only)."""
173
+ return _reconstruct_local(response_text, alias_map, target_format)
@@ -0,0 +1,47 @@
1
+ """Local-only token utilities; remote message counting is retired."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING, Any
6
+
7
+ from ..errors import CloakAPIError
8
+
9
+ if TYPE_CHECKING:
10
+ from ..async_client import AsyncCloakAPI
11
+ from ..client import CloakAPI
12
+
13
+
14
+ class TokensResource:
15
+ def __init__(self, client: CloakAPI) -> None:
16
+ self._client = client
17
+
18
+ def count(
19
+ self,
20
+ *,
21
+ provider: str,
22
+ model: str,
23
+ messages: list[dict[str, Any]],
24
+ all_providers: bool = False,
25
+ ) -> dict[str, Any]:
26
+ """Reject retired remote counting without sending message content."""
27
+ raise CloakAPIError(
28
+ "Remote token counting is unavailable; request content was not sent."
29
+ )
30
+
31
+
32
+ class AsyncTokensResource:
33
+ def __init__(self, client: AsyncCloakAPI) -> None:
34
+ self._client = client
35
+
36
+ async def count(
37
+ self,
38
+ *,
39
+ provider: str,
40
+ model: str,
41
+ messages: list[dict[str, Any]],
42
+ all_providers: bool = False,
43
+ ) -> dict[str, Any]:
44
+ """Async variant; reject without sending message content."""
45
+ raise CloakAPIError(
46
+ "Remote token counting is unavailable; request content was not sent."
47
+ )
cloakapi/review.py ADDED
@@ -0,0 +1,112 @@
1
+ """Review before a request leaves: the callback form and the step form.
2
+
3
+ Callback form (every hello world uses it)::
4
+
5
+ def review(text, info):
6
+ print(text) # the exact body that will be sent
7
+ return input("Send? ") == "y" # True sends, anything else stops
8
+
9
+ client = CloakAPI(review=review)
10
+
11
+ ``info`` is a :class:`~cloakapi.notices.ReviewInfo`: ``state`` (``ok`` or
12
+ ``degraded``), ``coverage`` and ``warnings``. A callback that returns ``True``
13
+ without showing anything is allowed; it is the one-liner for server-side use.
14
+
15
+ Step form, for an application with its own review screen::
16
+
17
+ prepared = client.messages.prepare(model=..., messages=[...])
18
+ show(prepared.text, prepared.warnings)
19
+ reply = client.send(client.approve(prepared))
20
+
21
+ ``send`` takes only the object ``approve`` returned for that ``prepared``.
22
+ Declining, or having no review at all, raises
23
+ :class:`~cloakapi.errors.ReviewRequiredError` before any network call.
24
+
25
+ ``review_callback`` (0.4.x) still works and receives a :class:`RelayReview`;
26
+ it is deprecated in favour of ``review``.
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ from collections.abc import Mapping
32
+ from dataclasses import dataclass, field
33
+ from types import MappingProxyType
34
+ from typing import Any
35
+
36
+ from .errors import ReviewRequiredError
37
+ from .notices import SendWarning
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class RelayReview:
42
+ """The exact tokenised JSON bytes and route that a reviewer is approving."""
43
+
44
+ method: str
45
+ url: str
46
+ body: bytes
47
+ headers: Mapping[str, str]
48
+
49
+ @classmethod
50
+ def create(cls, method: str, url: str, body: bytes, headers: dict[str, str]) -> RelayReview:
51
+ return cls(method, url, body, MappingProxyType(dict(headers)))
52
+
53
+
54
+ def require_approval(callback: object, request: RelayReview) -> None:
55
+ """Run the required synchronous approval callback before an egress request."""
56
+ if not callable(callback):
57
+ raise ReviewRequiredError()
58
+ try:
59
+ approved = callback(request)
60
+ except Exception:
61
+ raise ReviewRequiredError() from None
62
+ if approved is not True:
63
+ raise ReviewRequiredError()
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class Prepared:
68
+ """A request that is ready to be shown. Nothing has been sent.
69
+
70
+ ``text`` is the exact outgoing body. ``state`` is ``ok`` when every local
71
+ layer ran and ``degraded`` otherwise; ``coverage`` and ``warnings`` say why.
72
+ """
73
+
74
+ text: str
75
+ coverage: str
76
+ warnings: tuple[SendWarning, ...]
77
+ state: str
78
+ method: str = "POST"
79
+ url: str = ""
80
+ _handle: object = field(default_factory=object, repr=False, compare=False)
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class Approved:
85
+ """What :meth:`CloakAPI.approve` returns; the only thing ``send`` accepts."""
86
+
87
+ prepared: Prepared
88
+ text: str
89
+
90
+
91
+ def run_review(client: Any, built: Any) -> Any:
92
+ """Ask the caller's review for this request. Returns the callback's answer.
93
+
94
+ ``review(text, info)`` wins over the deprecated ``review_callback(request)``.
95
+ No review configured, or a callback that raises, is ``review_required``.
96
+ The answer may be awaitable (async client); :func:`check_review` judges it.
97
+ """
98
+ review = getattr(client, "review", None)
99
+ try:
100
+ if callable(review):
101
+ return review(built.text, built.info())
102
+ legacy = getattr(client, "review_callback", None)
103
+ if callable(legacy):
104
+ return legacy(built.review())
105
+ except Exception:
106
+ raise ReviewRequiredError() from None
107
+ raise ReviewRequiredError()
108
+
109
+
110
+ def check_review(answer: object) -> None:
111
+ if answer is not True:
112
+ raise ReviewRequiredError()