omnichar-sdk 0.0.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.
@@ -0,0 +1,71 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Read Omnichar Studio ``.char`` character files; images need the ``images`` extra."""
3
+
4
+ from .character import Character, CharacterInfo
5
+ from .charfile import (
6
+ FORMAT_VERSION,
7
+ MAGIC,
8
+ ORIGIN_HARVESTED,
9
+ ORIGIN_ORIGINAL,
10
+ ROLE_BODY,
11
+ ROLE_CLOTH,
12
+ ROLE_FACE,
13
+ ROLES,
14
+ CharChanged,
15
+ CharDoc,
16
+ CharError,
17
+ Manifest,
18
+ looks_like_char,
19
+ payload_key,
20
+ read,
21
+ )
22
+ from .lora import (
23
+ KEY_SUFFIXES,
24
+ KEY_WRAPPERS,
25
+ Lora,
26
+ Portability,
27
+ module_stem,
28
+ safe_output_name,
29
+ )
30
+ from .prompt import STYLES, prompt_prefix
31
+ from .references import FIT_MODES, SIZE_POLICIES, Reference, allocate_roles, common_size, fit_roles
32
+ from .sheet import reference_sheet, sheet_png
33
+
34
+ __version__ = "0.0.1"
35
+
36
+ __all__ = [
37
+ "FIT_MODES",
38
+ "KEY_SUFFIXES",
39
+ "KEY_WRAPPERS",
40
+ "FORMAT_VERSION",
41
+ "MAGIC",
42
+ "ORIGIN_HARVESTED",
43
+ "ORIGIN_ORIGINAL",
44
+ "ROLES",
45
+ "ROLE_BODY",
46
+ "ROLE_CLOTH",
47
+ "ROLE_FACE",
48
+ "SIZE_POLICIES",
49
+ "STYLES",
50
+ "CharChanged",
51
+ "CharDoc",
52
+ "CharError",
53
+ "Character",
54
+ "CharacterInfo",
55
+ "Lora",
56
+ "Manifest",
57
+ "Portability",
58
+ "Reference",
59
+ "__version__",
60
+ "allocate_roles",
61
+ "common_size",
62
+ "fit_roles",
63
+ "looks_like_char",
64
+ "module_stem",
65
+ "payload_key",
66
+ "prompt_prefix",
67
+ "reference_sheet",
68
+ "sheet_png",
69
+ "read",
70
+ "safe_output_name",
71
+ ]
@@ -0,0 +1,429 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """``Character``: one ``.char``, read a member at a time so a held handle cannot go stale."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import io
7
+ import struct
8
+ import zipfile
9
+ from collections.abc import Generator, Sequence
10
+ from contextlib import contextmanager
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+ from typing import TYPE_CHECKING, Any
14
+
15
+ from . import charfile as cf
16
+ from . import limits
17
+ from .lora import Lora, measure_portability, read_safetensors_header_stream
18
+ from .prompt import prompt_prefix
19
+ from .references import Reference, fit_roles
20
+ from .sheet import reference_sheet, sheet_png
21
+
22
+ if TYPE_CHECKING: # pragma: no cover
23
+ from PIL.Image import Image
24
+
25
+ #: PNG signature plus the IHDR chunk: width and height are at a fixed offset in the first 24 bytes.
26
+ _PNG_HEADER_BYTES = 24
27
+ _PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
28
+
29
+
30
+ @dataclass(frozen=True)
31
+ class CharacterInfo:
32
+ """Everything about a character that costs nothing to read."""
33
+
34
+ name: str
35
+ char_id: str
36
+ description: str
37
+ hints: list[str]
38
+ ref_count: int
39
+ ref_archs: list[str]
40
+ lora_archs: list[str]
41
+ format_version: int
42
+ created_at: int
43
+ modified_at: int
44
+ size_bytes: int
45
+
46
+
47
+ @contextmanager
48
+ def _memory_archive(data: bytes, label: str) -> Generator[zipfile.ZipFile]:
49
+ """A zip held in memory, raising the same error a file on disk would."""
50
+ try:
51
+ archive = zipfile.ZipFile(io.BytesIO(data), "r")
52
+ except zipfile.BadZipFile as error:
53
+ raise cf.CharError(
54
+ f"{label} is not a readable character file. It may have been truncated in "
55
+ "transfer; download it again."
56
+ ) from error
57
+ try:
58
+ yield archive
59
+ finally:
60
+ archive.close()
61
+
62
+
63
+ def _png_size(data: bytes) -> tuple[int, int]:
64
+ """Width and height from a PNG's IHDR, or zeroes when the bytes are not a PNG."""
65
+ if len(data) < _PNG_HEADER_BYTES or not data.startswith(_PNG_SIGNATURE):
66
+ return (0, 0)
67
+ width, height = struct.unpack(">II", data[16:24])
68
+ return (int(width), int(height))
69
+
70
+
71
+ class Character:
72
+ """A ``.char`` on disk or in memory. Construct with `open`, `from_bytes` or `from_file`."""
73
+
74
+ def __init__(
75
+ self,
76
+ manifest: cf.Manifest,
77
+ *,
78
+ path: Path | None = None,
79
+ data: bytes | None = None,
80
+ label: str = "",
81
+ manifest_sha: str = "",
82
+ stamp: tuple[int, int] | None = None,
83
+ size_bytes: int = 0,
84
+ ) -> None:
85
+ self._manifest = manifest
86
+ self._path = path
87
+ self._data = data
88
+ self._label = label
89
+ self._manifest_sha = manifest_sha
90
+ self._stamp = stamp
91
+ self._size_bytes = size_bytes
92
+
93
+ # --- construction -----------------------------------------------------------------------
94
+
95
+ @classmethod
96
+ def open(cls, path: Path | str) -> Character:
97
+ """Open a ``.char``, validating only its manifest."""
98
+ target = Path(path)
99
+ with cf.open_archive(target) as archive:
100
+ raw = cf.read_manifest_bytes(archive, target.name)
101
+ manifest = cf.parse_manifest(raw, target.name)
102
+ stat = target.stat()
103
+ return cls(
104
+ manifest,
105
+ path=target,
106
+ label=target.name,
107
+ manifest_sha=cf.sha256_bytes(raw),
108
+ stamp=(stat.st_mtime_ns, stat.st_size),
109
+ size_bytes=stat.st_size,
110
+ )
111
+
112
+ @classmethod
113
+ def from_bytes(cls, data: bytes, label: str = "character") -> Character:
114
+ """Open a ``.char`` already in memory, where nothing can change under it."""
115
+ with _memory_archive(data, label) as archive:
116
+ cf.check_archive(archive, label)
117
+ raw = cf.read_manifest_bytes(archive, label)
118
+ manifest = cf.parse_manifest(raw, label)
119
+ return cls(
120
+ manifest,
121
+ data=data,
122
+ label=label,
123
+ manifest_sha=cf.sha256_bytes(raw),
124
+ size_bytes=len(data),
125
+ )
126
+
127
+ @classmethod
128
+ def from_file(cls, stream: Any, label: str = "character") -> Character:
129
+ """Read a ``.char`` from a stream, bounded so an endless one cannot exhaust memory."""
130
+ cap = limits.MAX_TOTAL_UNCOMPRESSED_BYTES
131
+ data = stream.read(cap + 1)
132
+ if len(data) > cap:
133
+ raise cf.CharError(
134
+ f"{label} is larger than {cap} bytes, which no character reaches. "
135
+ "Do not open it; get the character from a source you trust."
136
+ )
137
+ return cls.from_bytes(data, label)
138
+
139
+ # --- identity ---------------------------------------------------------------------------
140
+
141
+ @property
142
+ def manifest(self) -> cf.Manifest:
143
+ return self._manifest
144
+
145
+ @property
146
+ def name(self) -> str:
147
+ return self._manifest.name or Path(self._label).stem
148
+
149
+ @property
150
+ def char_id(self) -> str:
151
+ return self._manifest.char_id
152
+
153
+ @property
154
+ def format_version(self) -> int:
155
+ """What the file declared, not what this build reads."""
156
+ return self._manifest.format_version
157
+
158
+ @property
159
+ def created_at(self) -> int:
160
+ return self._manifest.created_at
161
+
162
+ @property
163
+ def modified_at(self) -> int:
164
+ return self._manifest.modified_at
165
+
166
+ # --- member access ----------------------------------------------------------------------
167
+
168
+ @contextmanager
169
+ def _archive(self) -> Generator[zipfile.ZipFile]:
170
+ """An open archive, proven to still be the file this character was built from."""
171
+ if self._data is not None:
172
+ with _memory_archive(self._data, self._label) as archive:
173
+ yield archive
174
+ return
175
+ assert self._path is not None
176
+ stat = self._path.stat()
177
+ current = (stat.st_mtime_ns, stat.st_size)
178
+ with cf.open_archive(self._path) as archive:
179
+ if current != self._stamp:
180
+ raw = cf.read_manifest_bytes(archive, self._label)
181
+ if cf.sha256_bytes(raw) != self._manifest_sha:
182
+ raise cf.CharChanged(
183
+ f"{self._label} was replaced while it was open. Open it again to read "
184
+ "the new version."
185
+ )
186
+ self._stamp = current
187
+ yield archive
188
+
189
+ def _read(self, member: str) -> bytes:
190
+ """One member's bytes, refusing a nested archive."""
191
+ if not member:
192
+ raise cf.CharError(
193
+ f"{self._label} lists a file with no path in its manifest, so it cannot be read. "
194
+ "Export the character again from Omnichar Studio."
195
+ )
196
+ with self._archive() as archive:
197
+ try:
198
+ data = archive.read(member)
199
+ except KeyError:
200
+ raise self._missing(member) from None
201
+ return cf.check_member(member, data, self._label)
202
+
203
+ def _missing(self, member: str) -> cf.CharError:
204
+ return cf.CharError(
205
+ f"{self._label} has no {member!r}, which its manifest lists. The character is "
206
+ "incomplete; export it again from Omnichar Studio."
207
+ )
208
+
209
+ def _prefix(self, archive: zipfile.ZipFile, member: str, count: int) -> bytes:
210
+ """The first ``count`` bytes of a member, checked and decompressed no further than that."""
211
+ try:
212
+ with archive.open(member, "r") as stream:
213
+ data = stream.read(count)
214
+ except KeyError:
215
+ raise self._missing(member) from None
216
+ return cf.check_member(member, data, self._label)
217
+
218
+ # --- the facade -------------------------------------------------------------------------
219
+
220
+ def get_description(self) -> str:
221
+ """The locked character description, or an empty string when the file carries none."""
222
+ member = str(self._manifest.text.get("path") or "")
223
+ if not member:
224
+ return ""
225
+ return self._read(member).decode("utf-8", errors="replace")
226
+
227
+ def get_hints(self) -> list[str]:
228
+ return [str(hint) for hint in self._manifest.hints]
229
+
230
+ def get_ref_archs(self) -> list[str]:
231
+ """Architectures with a compiled reference set."""
232
+ return sorted(k for k in self._manifest.payloads if not k.endswith(f"-{cf.PAYLOAD_LORA}"))
233
+
234
+ def get_lora_archs(self) -> list[str]:
235
+ """Architectures with a trained adapter."""
236
+ suffix = f"-{cf.PAYLOAD_LORA}"
237
+ return sorted(k[: -len(suffix)] for k in self._manifest.payloads if k.endswith(suffix))
238
+
239
+ def get_info(self) -> CharacterInfo:
240
+ return CharacterInfo(
241
+ name=self.name,
242
+ char_id=self.char_id,
243
+ description=self.get_description(),
244
+ hints=self.get_hints(),
245
+ ref_count=len(self._manifest.refs),
246
+ ref_archs=self.get_ref_archs(),
247
+ lora_archs=self.get_lora_archs(),
248
+ format_version=self.format_version,
249
+ created_at=self.created_at,
250
+ modified_at=self.modified_at,
251
+ size_bytes=self._size_bytes,
252
+ )
253
+
254
+ def get_references(
255
+ self,
256
+ arch: str | None = None,
257
+ role: str | None = None,
258
+ origin: str | None = None,
259
+ limit: int | None = None,
260
+ ) -> list[Reference]:
261
+ """References in manifest order, which is what a prompt's positions refer to."""
262
+ if arch is not None and origin is not None:
263
+ raise ValueError(
264
+ "get_references takes arch or origin, not both. A compiled payload records no "
265
+ f"per-reference origin, so origin={origin!r} cannot be applied to arch={arch!r}. "
266
+ "Drop origin, or drop arch to read the original references."
267
+ )
268
+ if arch is None:
269
+ entries = list(self._manifest.refs)
270
+ else:
271
+ payload = self._manifest.payloads.get(arch)
272
+ if not isinstance(payload, dict):
273
+ raise cf.CharError(
274
+ f"{self.name} has no compiled references for {arch}. It has "
275
+ f"{', '.join(self.get_ref_archs()) or 'none'}."
276
+ )
277
+ entries = list(payload.get("files") or [])
278
+
279
+ refs = self._build_references(entries)
280
+ if origin is not None:
281
+ refs = [ref for ref in refs if ref.origin == origin]
282
+ if role is not None:
283
+ refs = [ref for ref in refs if ref.role == role]
284
+ if limit is not None:
285
+ refs = fit_roles(refs, limit)
286
+ return refs
287
+
288
+ def _build_references(self, entries: Sequence[dict[str, Any]]) -> list[Reference]:
289
+ """Reference objects, reading a PNG header only for entries that record no size."""
290
+ missing = [
291
+ str(e.get("path") or "")
292
+ for e in entries
293
+ if not (int(e.get("width") or 0) and int(e.get("height") or 0))
294
+ ]
295
+ sizes: dict[str, tuple[int, int]] = {}
296
+ if missing:
297
+ with self._archive() as archive:
298
+ for member in missing:
299
+ if not member:
300
+ continue
301
+ sizes[member] = _png_size(
302
+ self._prefix(archive, member, _PNG_HEADER_BYTES)
303
+ )
304
+ out: list[Reference] = []
305
+ for entry in entries:
306
+ path = str(entry.get("path") or "")
307
+ width = int(entry.get("width") or 0)
308
+ height = int(entry.get("height") or 0)
309
+ if not (width and height):
310
+ width, height = sizes.get(path, (0, 0))
311
+ out.append(
312
+ Reference(
313
+ path=path,
314
+ role=cf.role_of(entry),
315
+ origin=cf.origin_of(entry),
316
+ width=width,
317
+ height=height,
318
+ sha256=str(entry.get("sha256") or ""),
319
+ _read=self._read,
320
+ )
321
+ )
322
+ return out
323
+
324
+ def get_lora(self, arch: str | None = None) -> Lora | None:
325
+ """The adapter for ``arch``; with several and no ``arch`` it raises rather than guess."""
326
+ available = self.get_lora_archs()
327
+ if not available:
328
+ return None
329
+ if arch is None:
330
+ if len(available) > 1:
331
+ raise cf.CharError(
332
+ f"{self.name} carries adapters for {', '.join(available)}. "
333
+ "Name one with get_lora(arch=...)."
334
+ )
335
+ arch = available[0]
336
+ key = cf.payload_key(arch, cf.PAYLOAD_LORA)
337
+ entry = self._manifest.payloads.get(key)
338
+ if not isinstance(entry, dict):
339
+ return None
340
+ files = [str(f.get("path")) for f in entry.get("files") or [] if f.get("path")]
341
+ if not files:
342
+ return None
343
+ member = files[0]
344
+ raw_training = entry.get("training")
345
+ training: dict[str, Any] = raw_training if isinstance(raw_training, dict) else {}
346
+ filename = Path(member).name
347
+ keys = self._adapter_keys(member, filename)
348
+ verdict, reason = measure_portability(arch, keys)
349
+ return Lora(
350
+ arch=arch,
351
+ base=str(entry.get("base") or ""),
352
+ rank=int(training.get("rank") or 0),
353
+ steps=int(training.get("steps") or 0),
354
+ resolution=int(training.get("resolution") or 0),
355
+ strength=float(entry.get("strength") or 1.0),
356
+ filename=filename,
357
+ portability=verdict,
358
+ reason=reason,
359
+ _read=self._read,
360
+ _read_header=lambda: self._adapter_header(member, filename),
361
+ _member=member,
362
+ )
363
+
364
+ def _adapter_keys(self, member: str, label: str) -> list[str]:
365
+ """Tensor names from the adapter's header."""
366
+ return [k for k in self._adapter_header(member, label) if k != "__metadata__"]
367
+
368
+ def _adapter_header(self, member: str, label: str) -> dict[str, Any]:
369
+ """The adapter's header, decompressing no more of the member than the header itself."""
370
+ with self._archive() as archive:
371
+ # The nested-archive guard, before the header is streamed out of the member.
372
+ self._prefix(archive, member, len(limits.ZIP_MAGIC))
373
+ try:
374
+ with archive.open(member, "r") as stream:
375
+ header = read_safetensors_header_stream(stream, label)
376
+ except KeyError:
377
+ raise self._missing(member) from None
378
+ return header
379
+
380
+ def reference_sheet(
381
+ self,
382
+ arch: str | None = None,
383
+ role: str | None = None,
384
+ limit: int | None = None,
385
+ origin: str | None = None,
386
+ *,
387
+ first_position: int = 1,
388
+ **options: Any,
389
+ ) -> Image:
390
+ """References as one contact sheet, numbered from ``first_position`` as a prompt is."""
391
+ refs = self.get_references(arch=arch, role=role, origin=origin, limit=limit)
392
+ options.setdefault("title", self.name)
393
+ options.setdefault("subtitle", f"{len(refs)} references" + (f" · {arch}" if arch else ""))
394
+ return reference_sheet(refs, first_position=first_position, **options)
395
+
396
+ def reference_sheet_png(self, *args: Any, **options: Any) -> bytes:
397
+ """The contact sheet as PNG bytes."""
398
+ return sheet_png(self.reference_sheet(*args, **options))
399
+
400
+ def save_reference_sheet(self, path: Path | str, *args: Any, **options: Any) -> Path:
401
+ """Write the contact sheet to ``path`` as a PNG, adding the extension when it has none."""
402
+ target = Path(path)
403
+ if target.suffix.lower() != ".png":
404
+ target = target.with_suffix(".png")
405
+ target.parent.mkdir(parents=True, exist_ok=True)
406
+ target.write_bytes(self.reference_sheet_png(*args, **options))
407
+ return target
408
+
409
+ def get_prompt(
410
+ self,
411
+ style: str = "ordinal",
412
+ first_position: int = 1,
413
+ role_lines: bool = False,
414
+ count: int | None = None,
415
+ arch: str | None = None,
416
+ ) -> str:
417
+ """Prompt text naming the positions this character's references will occupy."""
418
+ refs = self.get_references(arch=arch, limit=count)
419
+ return prompt_prefix(
420
+ self.name,
421
+ self.get_description(),
422
+ [ref.role for ref in refs],
423
+ first_position=first_position,
424
+ style=style,
425
+ role_lines=role_lines,
426
+ )
427
+
428
+ def __repr__(self) -> str:
429
+ return f"<Character {self.name!r} refs={len(self._manifest.refs)}>"