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,176 @@
1
+ """File attachments, tokenised on-device before egress.
2
+
3
+ This module never creates a raw attachment wire payload. If the native
4
+ client-side engine is unavailable, attachment preparation raises
5
+ :class:`cloakapi.engine.EngineError`; the caller must install or build a
6
+ compatible engine and retry. The reduced-coverage text opt-in does not apply to
7
+ files or images.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import base64
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ from .engine import get_engine
18
+ from .surrogate_mode import SurrogateMode
19
+
20
+ # Client-side mirror of apps/gateway/config/privacy.php `markitdown.*` defaults.
21
+ MAX_FILE_BYTES = 20 * 1024 * 1024
22
+ MAX_FILES = 5
23
+ FORMAT_ALLOWLIST = frozenset(
24
+ {
25
+ "pdf", "docx", "doc", "pptx", "ppt", "xlsx", "xls", "csv",
26
+ "html", "htm", "txt", "md", "json", "xml", "epub", "ipynb", "eml", "msg",
27
+ # Images — OCR'd + tokenised ON-DEVICE by the engine's file-pipeline.
28
+ "png", "jpg", "jpeg", "webp", "gif", "bmp", "tif", "tiff",
29
+ }
30
+ )
31
+
32
+
33
+ class AttachmentReviewRequiredError(ValueError):
34
+ """A convenience attachment cannot be relayed before its text is reviewed."""
35
+
36
+
37
+ ATTACHMENT_REVIEW_MESSAGE = (
38
+ "CloakAPI will not relay an attachment before you can review its on-device "
39
+ "tokenised text. Call client.tokenize_file(data, ...), review the returned "
40
+ "text, then send that reviewed text in messages. No attachment bytes were sent."
41
+ )
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class Attachment:
46
+ """A local file attachment awaiting on-device tokenisation."""
47
+
48
+ filename: str
49
+ content_b64: str
50
+ mime_type: str | None = None
51
+
52
+ def decoded_bytes(self) -> bytes:
53
+ return base64.b64decode(self.content_b64)
54
+
55
+
56
+ def _extension_of(filename: str) -> str:
57
+ _, _, ext = filename.rpartition(".")
58
+ return ext.lower() if "." in filename else ""
59
+
60
+
61
+ def _oversized_attachment_error() -> ValueError:
62
+ cap_mb = MAX_FILE_BYTES // 1024 // 1024
63
+ return ValueError(
64
+ f"Attachment exceeds the {cap_mb} MB size limit. (attachment_too_large)"
65
+ )
66
+
67
+
68
+ def validate_attachment(attachment: Attachment) -> None:
69
+ """Fail-fast client-side cap check (mirrors the TS SDK / gateway 422 shapes)."""
70
+ ext = _extension_of(attachment.filename)
71
+ if not ext or ext not in FORMAT_ALLOWLIST:
72
+ raise ValueError(
73
+ "Attachment has a disallowed type. "
74
+ f"Allowed: {', '.join(sorted(FORMAT_ALLOWLIST))}. (attachment_mime_disallowed)"
75
+ )
76
+ # Byte length from base64 without decoding.
77
+ clean = attachment.content_b64.rstrip("=")
78
+ byte_len = (len(clean) * 3) // 4
79
+ if byte_len > MAX_FILE_BYTES:
80
+ raise _oversized_attachment_error()
81
+
82
+
83
+ def validate_attachments(attachments: list[Attachment]) -> None:
84
+ if len(attachments) > MAX_FILES:
85
+ raise ValueError(
86
+ f"Too many attachments. Maximum {MAX_FILES} file(s) per request. "
87
+ f"(attachment_count_exceeded)"
88
+ )
89
+ for a in attachments:
90
+ validate_attachment(a)
91
+
92
+
93
+ def attachment_from_bytes(filename: str, data: bytes, mime_type: str | None = None) -> Attachment:
94
+ """Build an :class:`Attachment` from raw bytes, validating client-side caps."""
95
+ att = Attachment(
96
+ filename=filename,
97
+ content_b64=base64.b64encode(data).decode("ascii"),
98
+ mime_type=mime_type,
99
+ )
100
+ validate_attachment(att)
101
+ return att
102
+
103
+
104
+ def attachment_from_file(path: str | Path, mime_type: str | None = None) -> Attachment:
105
+ """Build an :class:`Attachment` by reading a file from disk."""
106
+ p = Path(path)
107
+ if p.stat().st_size > MAX_FILE_BYTES:
108
+ raise _oversized_attachment_error()
109
+ # Bound the read too: the file can grow after stat(), and read_bytes() would
110
+ # otherwise allocate the entire local file before the later cap check.
111
+ with p.open("rb") as source:
112
+ data = source.read(MAX_FILE_BYTES + 1)
113
+ if len(data) > MAX_FILE_BYTES:
114
+ raise _oversized_attachment_error()
115
+ return attachment_from_bytes(p.name, data, mime_type)
116
+
117
+
118
+ def prepare_attachments(
119
+ attachments: list[Attachment],
120
+ *,
121
+ names: list[str] | None = None,
122
+ mode: SurrogateMode | None = None,
123
+ bindings: dict[str, Any] | None = None,
124
+ ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, str], dict[str, str]]:
125
+ """
126
+ Tokenise an ``attachments[]`` list locally for a caller-managed review flow.
127
+
128
+ Returns ``(local_message_blocks, server_attachments, token_map, headers)``:
129
+
130
+ * ``local_message_blocks`` — extra ``messages[]`` entries carrying the
131
+ LOCALLY tokenised markdown.
132
+ * ``server_attachments`` — always empty; raw file data is never forwarded.
133
+ * ``token_map`` — ``replacement-string -> original`` pairs discovered
134
+ locally (works in BOTH surrogate modes — see engine._detok_table), to
135
+ merge into the client map so the reply is detokenised.
136
+ * ``headers`` — request headers flagging local processing.
137
+
138
+ This helper does not send data. Callers must let the user review the returned
139
+ markdown before relaying it. If the engine is absent, this raises before any
140
+ network request. No reduced text-coverage override can enable raw file egress.
141
+ """
142
+ validate_attachments(attachments)
143
+
144
+ engine = get_engine()
145
+ if engine is not None:
146
+ blocks: list[dict[str, Any]] = []
147
+ token_map: dict[str, str] = {}
148
+ for att in attachments:
149
+ result = engine.tokenise_file(
150
+ att.decoded_bytes(),
151
+ mime=att.mime_type,
152
+ filename=att.filename,
153
+ names=names,
154
+ mode=mode,
155
+ bindings=bindings,
156
+ )
157
+ # Advance the SHARED ledger in place, so an entity that appears in
158
+ # both an attachment and the prompt gets ONE stand-in, and so the
159
+ # next turn keeps it. (`bindings is None` = single-message scope,
160
+ # which the engine then reports honestly.)
161
+ if bindings is not None:
162
+ bindings.clear()
163
+ bindings.update(result.bindings)
164
+ blocks.append(
165
+ {
166
+ "role": "user",
167
+ "content": [{"type": "text", "text": f"# Attached document\n\n{result.markdown}"}],
168
+ }
169
+ )
170
+ token_map.update(result.token_map)
171
+ return blocks, [], token_map, {"X-CloakAPI-Attachment-Mode": "local"}
172
+
173
+ from .degraded import engine_unavailable_message
174
+ from .engine import EngineError
175
+
176
+ raise EngineError(engine_unavailable_message("tokenise file attachments on-device"))
cloakapi/cli.py ADDED
@@ -0,0 +1,245 @@
1
+ """
2
+ CloakAPI command-line interface.
3
+
4
+ Entry point: ``cloakapi`` (registered via pyproject.toml console_scripts).
5
+
6
+ Commands:
7
+ cloakapi ping Verify connectivity and API key validity.
8
+ cloakapi chat One-shot chat via Anthropic-compatible endpoint.
9
+ cloakapi stream Streaming chat demo.
10
+ cloakapi config show Show current credentials.
11
+ cloakapi config set Set api_key / base_url in ~/.cloakapi/config.json.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import os
17
+ from typing import Annotated
18
+
19
+ import typer
20
+
21
+ app = typer.Typer(
22
+ name="cloakapi",
23
+ help="CloakAPI CLI — a client for the CloakAPI gateway.",
24
+ no_args_is_help=True,
25
+ add_completion=False,
26
+ )
27
+
28
+ config_app = typer.Typer(help="Manage local credentials (~/.cloakapi/config.json).")
29
+ app.add_typer(config_app, name="config")
30
+
31
+ # ── helpers ──────────────────────────────────────────────────────────────────
32
+
33
+
34
+ def _get_client() -> CloakAPI: # type: ignore[name-defined]
35
+ from cloakapi.client import CloakAPI # local import keeps CLI startup fast
36
+
37
+ return CloakAPI()
38
+
39
+
40
+ def _rich_print(text: str, style: str = "") -> None:
41
+ """Lazy import of rich.console to avoid import-time cost."""
42
+ from rich.console import Console # lazy
43
+
44
+ console = Console()
45
+ console.print(text, style=style)
46
+
47
+
48
+ def _err_print(text: str) -> None:
49
+ """Print to stderr via rich."""
50
+ from rich.console import Console
51
+
52
+ Console(stderr=True).print(text)
53
+
54
+
55
+ # ── ping ─────────────────────────────────────────────────────────────────────
56
+
57
+
58
+ @app.command()
59
+ def ping() -> None:
60
+ """Verify API key validity and gateway connectivity."""
61
+ from rich.console import Console
62
+
63
+ console = Console()
64
+ try:
65
+ client = _get_client()
66
+ # Hit the models endpoint (no usage, just auth check)
67
+ resp = client._unsafe_raw_sync_request("GET", "/api/v1/models")
68
+ console.print(
69
+ f"[bold green]OK[/bold green] Connected to [cyan]{client.base_url}[/cyan] "
70
+ "(API key accepted)"
71
+ )
72
+ data = resp.json()
73
+ if isinstance(data, dict) and "data" in data:
74
+ model_ids = [m.get("id", "?") for m in data["data"][:5]]
75
+ console.print(f"Available models: {', '.join(model_ids)}")
76
+ except Exception as exc: # noqa: BLE001
77
+ _err_print(f"[bold red]FAIL[/bold red] {exc}")
78
+ raise typer.Exit(code=1)
79
+
80
+
81
+ # ── chat ─────────────────────────────────────────────────────────────────────
82
+
83
+
84
+ @app.command()
85
+ def chat(
86
+ model: Annotated[str, typer.Option("--model", "-m", help="Model ID")] = "claude-sonnet-4-6",
87
+ prompt: Annotated[str, typer.Option("--prompt", "-p", help="User prompt")] = "",
88
+ tokenize: Annotated[
89
+ bool,
90
+ typer.Option(
91
+ "--tokenize/--no-tokenize",
92
+ help="On-device PII tokenization (default on; required by the gateway).",
93
+ ),
94
+ ] = True,
95
+ ) -> None:
96
+ """Send a one-shot chat message and print the response."""
97
+ from rich.console import Console
98
+ from rich.markdown import Markdown
99
+
100
+ from cloakapi.client import CloakAPI
101
+ from cloakapi.types import Message
102
+
103
+ console = Console()
104
+
105
+ if not prompt:
106
+ prompt = typer.prompt("Prompt")
107
+
108
+ try:
109
+ client = CloakAPI(tokenize=tokenize)
110
+ result = client.messages.create(
111
+ model=model,
112
+ messages=[{"role": "user", "content": prompt}],
113
+ )
114
+ # messages.create(stream=False) always returns Message
115
+ msg: Message = result # type: ignore[assignment]
116
+ console.print(Markdown(msg.text()))
117
+ console.print(
118
+ f"\n[dim]tokens: {msg.usage.input_tokens} in / {msg.usage.output_tokens} out | "
119
+ f"stop: {msg.stop_reason}[/dim]"
120
+ )
121
+ except Exception as exc: # noqa: BLE001
122
+ _err_print(f"[bold red]Error:[/bold red] {exc}")
123
+ raise typer.Exit(code=1)
124
+
125
+
126
+ # ── stream ────────────────────────────────────────────────────────────────────
127
+
128
+
129
+ @app.command()
130
+ def stream(
131
+ model: Annotated[str, typer.Option("--model", "-m", help="Model ID")] = "claude-sonnet-4-6",
132
+ prompt: Annotated[str, typer.Option("--prompt", "-p", help="User prompt")] = "",
133
+ tokenize: Annotated[bool, typer.Option("--tokenize/--no-tokenize")] = True,
134
+ ) -> None:
135
+ """Stream a chat response token-by-token."""
136
+ from rich.console import Console
137
+
138
+ from cloakapi.client import CloakAPI
139
+ from cloakapi.types import ContentBlockDelta
140
+
141
+ console = Console()
142
+
143
+ if not prompt:
144
+ prompt = typer.prompt("Prompt")
145
+
146
+ try:
147
+ client = CloakAPI(tokenize=tokenize)
148
+ with console.status("Connecting..."):
149
+ events = client.messages.create(
150
+ model=model,
151
+ messages=[{"role": "user", "content": prompt}],
152
+ stream=True,
153
+ )
154
+ for event in events:
155
+ if isinstance(event, ContentBlockDelta):
156
+ delta = event.delta
157
+ if isinstance(delta, dict) and delta.get("type") == "text_delta":
158
+ console.print(delta.get("text", ""), end="")
159
+ console.print() # newline after stream
160
+ except Exception as exc: # noqa: BLE001
161
+ _err_print(f"\n[bold red]Stream error:[/bold red] {exc}")
162
+ raise typer.Exit(code=1)
163
+
164
+
165
+ # ── config ────────────────────────────────────────────────────────────────────
166
+
167
+
168
+ @config_app.command("show")
169
+ def config_show() -> None:
170
+ """Show currently configured credentials."""
171
+ from rich.console import Console
172
+ from rich.table import Table
173
+
174
+ from cloakapi.config import _CONFIG_FILE, DEFAULT_BASE_URL, _load_config_file
175
+
176
+ console = Console()
177
+
178
+ cfg = _load_config_file()
179
+ env_key = os.environ.get("CLOAKAPI_API_KEY", "")
180
+ env_url = os.environ.get("CLOAKAPI_BASE_URL", "")
181
+
182
+ table = Table(title="CloakAPI Configuration", show_header=True)
183
+ table.add_column("Source", style="dim")
184
+ table.add_column("Key")
185
+ table.add_column("Value")
186
+
187
+ raw_key = cfg.get("api_key", "")
188
+ masked_key = "****" if raw_key else "(not set)"
189
+ table.add_row("config file", "api_key", masked_key)
190
+ table.add_row("config file", "base_url", cfg.get("base_url", DEFAULT_BASE_URL))
191
+
192
+ if env_key:
193
+ table.add_row("env", "CLOAKAPI_API_KEY", "****")
194
+ if env_url:
195
+ table.add_row("env", "CLOAKAPI_BASE_URL", env_url)
196
+
197
+ console.print(table)
198
+ console.print(f"\nConfig file: [cyan]{_CONFIG_FILE}[/cyan]")
199
+
200
+
201
+ @config_app.command("set")
202
+ def config_set(
203
+ api_key: Annotated[str | None, typer.Option("--api-key", help="API key to save")] = None,
204
+ base_url: Annotated[str | None, typer.Option("--base-url", help="Gateway base URL")] = None,
205
+ ) -> None:
206
+ """
207
+ Save credentials to ~/.cloakapi/config.json.
208
+
209
+ Example::
210
+
211
+ cloakapi config set --api-key cloak_abc123
212
+ cloakapi config set --base-url https://api.cloakapi.io
213
+ """
214
+ from rich.console import Console
215
+
216
+ from cloakapi.config import _save_config_file
217
+
218
+ console = Console()
219
+
220
+ updates: dict[str, str] = {}
221
+ if api_key:
222
+ updates["api_key"] = api_key
223
+ if base_url:
224
+ updates["base_url"] = base_url.rstrip("/")
225
+
226
+ if not updates:
227
+ console.print("[yellow]Nothing to set. Use --api-key or --base-url.[/yellow]")
228
+ raise typer.Exit()
229
+
230
+ _save_config_file(updates)
231
+ console.print("[bold green]Saved.[/bold green]")
232
+ for k, v in updates.items():
233
+ display = "****" if k == "api_key" else v
234
+ console.print(f" {k} = {display}")
235
+
236
+
237
+ # ── entry point ───────────────────────────────────────────────────────────────
238
+
239
+
240
+ def main() -> None:
241
+ app()
242
+
243
+
244
+ if __name__ == "__main__":
245
+ main()