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.
- LICENSE +202 -0
- NOTICE +18 -0
- THIRD-PARTY-NOTICES.md +22 -0
- TRADEMARKS.md +19 -0
- cloakapi/__init__.py +271 -0
- cloakapi/_disclosure/clk.txt +11 -0
- cloakapi/_disclosure/clk_message.txt +11 -0
- cloakapi/_disclosure/cloak_angle.txt +16 -0
- cloakapi/_disclosure/cloak_angle_message.txt +16 -0
- cloakapi/_http.py +443 -0
- cloakapi/_pretokenised.py +134 -0
- cloakapi/_relay.py +213 -0
- cloakapi/_release.py +30 -0
- cloakapi/_request_strings.py +1267 -0
- cloakapi/_ruleset/patterns.json +2238 -0
- cloakapi/_stream_detok.py +788 -0
- cloakapi/_version.py +31 -0
- cloakapi/async_client.py +704 -0
- cloakapi/attachments.py +176 -0
- cloakapi/cli.py +245 -0
- cloakapi/client.py +848 -0
- cloakapi/config.py +491 -0
- cloakapi/coverage.py +21 -0
- cloakapi/degraded.py +196 -0
- cloakapi/disclosure.py +334 -0
- cloakapi/engine.py +922 -0
- cloakapi/errors.py +304 -0
- cloakapi/notices.py +142 -0
- cloakapi/pii/__init__.py +4 -0
- cloakapi/pii/_checksum.py +510 -0
- cloakapi/pii/_ruleset.py +131 -0
- cloakapi/pii/patterns.py +1713 -0
- cloakapi/pii/rulefile.py +738 -0
- cloakapi/pii/tokenizer.py +537 -0
- cloakapi/posture.py +112 -0
- cloakapi/py.typed +1 -0
- cloakapi/receipts.py +605 -0
- cloakapi/resources/__init__.py +32 -0
- cloakapi/resources/admin.py +104 -0
- cloakapi/resources/buffer.py +54 -0
- cloakapi/resources/chat.py +293 -0
- cloakapi/resources/detect.py +115 -0
- cloakapi/resources/messages.py +260 -0
- cloakapi/resources/models.py +58 -0
- cloakapi/resources/receipts.py +252 -0
- cloakapi/resources/reconstruct.py +173 -0
- cloakapi/resources/tokens.py +47 -0
- cloakapi/review.py +112 -0
- cloakapi/streaming.py +446 -0
- cloakapi/surrogate_mode.py +308 -0
- cloakapi/types.py +284 -0
- cloakapi-0.5.1.dist-info/METADATA +441 -0
- cloakapi-0.5.1.dist-info/RECORD +61 -0
- cloakapi-0.5.1.dist-info/WHEEL +4 -0
- cloakapi-0.5.1.dist-info/entry_points.txt +2 -0
- cloakapi-0.5.1.dist-info/licenses/LICENSE +202 -0
- cloakapi-0.5.1.dist-info/licenses/NOTICE +18 -0
- licenses/Apache-2.0.txt +202 -0
- licenses/CC-BY-4.0.txt +104 -0
- licenses/MIT-Faker.txt +21 -0
- 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()
|