dinkster-api 0.0.2__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.
- dinkster_api/__init__.py +9 -0
- dinkster_api/py.typed +0 -0
- dinkster_api/v1.py +935 -0
- dinkster_api-0.0.2.dist-info/METADATA +16 -0
- dinkster_api-0.0.2.dist-info/RECORD +238 -0
- dinkster_api-0.0.2.dist-info/WHEEL +4 -0
- dinkster_api-0.0.2.dist-info/entry_points.txt +2 -0
- dinkster_assets/__init__.py +337 -0
- dinkster_assets/acquire.py +226 -0
- dinkster_assets/acquisition_plan.py +145 -0
- dinkster_assets/audio.py +119 -0
- dinkster_assets/catalog.py +156 -0
- dinkster_assets/component_manifest.py +110 -0
- dinkster_assets/declared.py +218 -0
- dinkster_assets/fetch.py +495 -0
- dinkster_assets/guess.py +136 -0
- dinkster_assets/identity.py +72 -0
- dinkster_assets/integrity.py +310 -0
- dinkster_assets/json_metadata.py +41 -0
- dinkster_assets/kind.py +52 -0
- dinkster_assets/latent_format.py +346 -0
- dinkster_assets/library.py +816 -0
- dinkster_assets/media.py +1385 -0
- dinkster_assets/migrations/env.py +38 -0
- dinkster_assets/migrations/script.py.mako +28 -0
- dinkster_assets/migrations/versions/0001_asset_records_create_asset_record_catalog.py +109 -0
- dinkster_assets/migrations/versions/0002_asset_observations.py +36 -0
- dinkster_assets/model.py +242 -0
- dinkster_assets/mounts.py +1278 -0
- dinkster_assets/need.py +168 -0
- dinkster_assets/pack_assets.py +217 -0
- dinkster_assets/probe.py +118 -0
- dinkster_assets/provenance.py +254 -0
- dinkster_assets/public_acquisition.py +424 -0
- dinkster_assets/py.typed +0 -0
- dinkster_assets/records.py +899 -0
- dinkster_assets/resolution.py +778 -0
- dinkster_assets/resolver_index.py +364 -0
- dinkster_assets/resolver_subscription.py +1149 -0
- dinkster_assets/save_target.py +139 -0
- dinkster_assets/schema.py +73 -0
- dinkster_assets/selections.py +256 -0
- dinkster_assets/transport.py +243 -0
- dinkster_assets/value.py +258 -0
- dinkster_assets/vault.py +276 -0
- dinkster_assets/writer.py +765 -0
- dinkster_caches/__init__.py +19 -0
- dinkster_caches/cas.py +310 -0
- dinkster_caches/disk.py +330 -0
- dinkster_caches/layered.py +150 -0
- dinkster_caches/memory.py +208 -0
- dinkster_caches/py.typed +0 -0
- dinkster_caches/wire.py +346 -0
- dinkster_image_document/__init__.py +39 -0
- dinkster_image_document/blend.py +264 -0
- dinkster_image_document/compat.py +211 -0
- dinkster_image_document/document.py +374 -0
- dinkster_image_document/format.py +569 -0
- dinkster_image_document/interchange.py +572 -0
- dinkster_image_document/py.typed +1 -0
- dinkster_image_document/render.py +455 -0
- dinkster_inference_wire/__init__.py +141 -0
- dinkster_inference_wire/camera_wire.py +127 -0
- dinkster_inference_wire/conditioning.py +752 -0
- dinkster_inference_wire/conditioning_wire.py +1143 -0
- dinkster_inference_wire/devices.py +285 -0
- dinkster_inference_wire/generation.py +446 -0
- dinkster_inference_wire/hook_values.py +168 -0
- dinkster_inference_wire/ic_lora_parameters.py +69 -0
- dinkster_inference_wire/latents.py +244 -0
- dinkster_inference_wire/media_wire.py +169 -0
- dinkster_inference_wire/openai_generation.py +1035 -0
- dinkster_inference_wire/pose_keypoint.py +83 -0
- dinkster_inference_wire/process.py +33 -0
- dinkster_inference_wire/py.typed +0 -0
- dinkster_inference_wire/registry.py +116 -0
- dinkster_inference_wire/sam3_wire.py +68 -0
- dinkster_inference_wire/sampling_wire.py +279 -0
- dinkster_inference_wire/sources.py +399 -0
- dinkster_inference_wire/spaces.py +344 -0
- dinkster_inference_wire/sparse.py +372 -0
- dinkster_inference_wire/splat_wire.py +23 -0
- dinkster_inference_wire/types.py +256 -0
- dinkster_inference_wire/vision_wire.py +53 -0
- dinkster_inference_wire/voxel_wire.py +72 -0
- dinkster_inference_wire/wan_wire.py +93 -0
- dinkster_inference_wire/weights.py +219 -0
- dinkster_memory/__init__.py +92 -0
- dinkster_memory/accelerator.py +96 -0
- dinkster_memory/budgets.py +96 -0
- dinkster_memory/details.py +91 -0
- dinkster_memory/governor.py +554 -0
- dinkster_memory/leases.py +176 -0
- dinkster_memory/py.typed +0 -0
- dinkster_memory/release.py +131 -0
- dinkster_memory/reported.py +101 -0
- dinkster_memory/reservations.py +101 -0
- dinkster_memory/resident.py +600 -0
- dinkster_memory/system.py +614 -0
- dinkster_memory/tenants.py +67 -0
- dinkster_protocol/__init__.py +1008 -0
- dinkster_protocol/attention.py +652 -0
- dinkster_protocol/extension_contribution_kinds.json +21 -0
- dinkster_protocol/extension_contribution_kinds.py +43 -0
- dinkster_protocol/extensions.py +742 -0
- dinkster_protocol/frontend_modules.py +145 -0
- dinkster_protocol/multigpu.py +107 -0
- dinkster_protocol/pack_surfaces.py +489 -0
- dinkster_protocol/payload.py +63 -0
- dinkster_protocol/preview.py +86 -0
- dinkster_protocol/py.typed +0 -0
- dinkster_protocol/result_algebra.py +380 -0
- dinkster_protocol/result_document.py +244 -0
- dinkster_protocol/run_control.py +96 -0
- dinkster_protocol/training.py +399 -0
- dinkster_protocol/workgroup.py +1014 -0
- dinkster_registry/__init__.py +135 -0
- dinkster_registry/admission.py +372 -0
- dinkster_registry/artifact.py +128 -0
- dinkster_registry/composition.py +152 -0
- dinkster_registry/grants.py +206 -0
- dinkster_registry/install.py +1017 -0
- dinkster_registry/model.py +414 -0
- dinkster_registry/principals.py +494 -0
- dinkster_registry/py.typed +0 -0
- dinkster_schema/__init__.py +347 -0
- dinkster_schema/capture.py +240 -0
- dinkster_schema/coerce.py +186 -0
- dinkster_schema/comfy_alias.py +496 -0
- dinkster_schema/comfy_group.py +768 -0
- dinkster_schema/elaborate.py +676 -0
- dinkster_schema/execution.py +24 -0
- dinkster_schema/expansion.py +123 -0
- dinkster_schema/log.py +206 -0
- dinkster_schema/media.py +77 -0
- dinkster_schema/model.py +2920 -0
- dinkster_schema/names.py +25 -0
- dinkster_schema/node.py +137 -0
- dinkster_schema/output_descriptors.py +63 -0
- dinkster_schema/py.typed +0 -0
- dinkster_schema/replace.py +1853 -0
- dinkster_schema/reporting.py +441 -0
- dinkster_schema/solve.py +178 -0
- dinkster_schema/wire.py +1876 -0
- dinkster_values/__init__.py +625 -0
- dinkster_values/_media_array.py +7 -0
- dinkster_values/absent.py +77 -0
- dinkster_values/asset_folders.py +64 -0
- dinkster_values/assets.py +106 -0
- dinkster_values/audio_codec.py +594 -0
- dinkster_values/audio_lazy.py +871 -0
- dinkster_values/builtin_types.py +181 -0
- dinkster_values/curve.py +260 -0
- dinkster_values/detection_codec.py +286 -0
- dinkster_values/image_codec.py +691 -0
- dinkster_values/image_components.py +219 -0
- dinkster_values/latent_codec.py +514 -0
- dinkster_values/limits.py +52 -0
- dinkster_values/lists.py +216 -0
- dinkster_values/media_containers.py +70 -0
- dinkster_values/model.py +417 -0
- dinkster_values/model3d_codec.py +167 -0
- dinkster_values/names.py +168 -0
- dinkster_values/pins.py +77 -0
- dinkster_values/py.typed +0 -0
- dinkster_values/registry.py +1105 -0
- dinkster_values/resident.py +210 -0
- dinkster_values/resources.py +210 -0
- dinkster_values/splat_codec.py +477 -0
- dinkster_values/storage.py +133 -0
- dinkster_values/streams.py +241 -0
- dinkster_values/svg_codec.py +120 -0
- dinkster_values/timeline_video.py +68 -0
- dinkster_values/tuples.py +61 -0
- dinkster_values/video_codec.py +897 -0
- dinkster_values/video_document.py +315 -0
- dinkster_values/video_edits.py +253 -0
- dinkster_values/video_probe.py +221 -0
- dinkster_video/__init__.py +58 -0
- dinkster_video/document.py +352 -0
- dinkster_video/formats.py +722 -0
- dinkster_video/image_math.py +175 -0
- dinkster_video/preview/dinkster-pack.toml +36 -0
- dinkster_video/preview/src/dinkster_video_preview/__init__.py +84 -0
- dinkster_video/preview/src/dinkster_video_preview/preview.js +45 -0
- dinkster_video/py.typed +1 -0
- dinkster_video/runtime.py +1561 -0
- dinkster_video/timeline.py +576 -0
- dinkster_video/timeline_runtime.py +305 -0
- dinkster_video_preview/__init__.py +84 -0
- dinkster_video_preview/preview.js +45 -0
- dinkster_workers/__init__.py +207 -0
- dinkster_workers/_doctor_probe.py +359 -0
- dinkster_workers/accelerator.py +156 -0
- dinkster_workers/aimdo_bootstrap.py +81 -0
- dinkster_workers/backend_env.py +1485 -0
- dinkster_workers/blobs.py +402 -0
- dinkster_workers/boundary.py +1918 -0
- dinkster_workers/catalog.py +182 -0
- dinkster_workers/devices.py +164 -0
- dinkster_workers/diagnostics.py +64 -0
- dinkster_workers/dispatch.py +298 -0
- dinkster_workers/doctor.py +1382 -0
- dinkster_workers/egress.py +344 -0
- dinkster_workers/error_hints.py +175 -0
- dinkster_workers/execution.py +160 -0
- dinkster_workers/governed.py +123 -0
- dinkster_workers/headroom.py +156 -0
- dinkster_workers/host.py +3116 -0
- dinkster_workers/in_process.py +1325 -0
- dinkster_workers/interpreter.py +84 -0
- dinkster_workers/isolated.py +862 -0
- dinkster_workers/launch.py +72 -0
- dinkster_workers/manifest.py +3332 -0
- dinkster_workers/media.py +196 -0
- dinkster_workers/pack_environment.py +473 -0
- dinkster_workers/pack_lock.py +359 -0
- dinkster_workers/placement.py +215 -0
- dinkster_workers/preview_artifacts.py +233 -0
- dinkster_workers/produced_assets.py +218 -0
- dinkster_workers/provision.py +597 -0
- dinkster_workers/py.typed +0 -0
- dinkster_workers/relay.py +762 -0
- dinkster_workers/remote.py +921 -0
- dinkster_workers/resume.py +490 -0
- dinkster_workers/routing.py +134 -0
- dinkster_workers/run_control.py +275 -0
- dinkster_workers/sandbox.py +798 -0
- dinkster_workers/saved_artifacts.py +275 -0
- dinkster_workers/service.py +593 -0
- dinkster_workers/session.py +2605 -0
- dinkster_workers/single_job_multi_gpu.py +7 -0
- dinkster_workers/staging.py +230 -0
- dinkster_workers/transport.py +161 -0
- dinkster_workers/workgroup.py +729 -0
- dinkster_workers/workgroup_compose.py +135 -0
- dinkster_workers/workgroup_config.py +196 -0
- dinkster_workers/workgroup_session.py +340 -0
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
"""Process-resident values: the objects never cross the boundary, stubs do.
|
|
2
|
+
|
|
3
|
+
A loaded model, text encoder, or codec is gigabytes of device state -
|
|
4
|
+
encoding it with the default pickle codec would be a catastrophe (huge
|
|
5
|
+
transfer, and unpicklable on a torch-less parent). Instead, resident types
|
|
6
|
+
register a codec that encodes a *resident id*: the object stays in the
|
|
7
|
+
holding process's residency table, other processes carry an interrogable
|
|
8
|
+
stub, and when the stub comes back as a later invocation's input the codec
|
|
9
|
+
resolves it from the table.
|
|
10
|
+
|
|
11
|
+
This is the engine-level ResourceHandle's identity-crosses/content-stays
|
|
12
|
+
shape, implemented entirely with the public TypeRegistry codec hooks - any
|
|
13
|
+
pack or package can register a resident type without touching engine or
|
|
14
|
+
worker code. One limit is deliberate:
|
|
15
|
+
|
|
16
|
+
- fingerprints are per-process resident ids, so cross-run caches will not
|
|
17
|
+
hit on resident values (the loader's own cache key still hits because it
|
|
18
|
+
is built from the loader's inputs).
|
|
19
|
+
|
|
20
|
+
A bare ResidencyTable holds strong references until the process exits. A
|
|
21
|
+
production residency pool may coordinate reference invalidation and remove
|
|
22
|
+
an owner together with all resident values that depend on it.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import json
|
|
28
|
+
import uuid
|
|
29
|
+
from collections.abc import Callable, Mapping
|
|
30
|
+
from typing import cast
|
|
31
|
+
|
|
32
|
+
from .model import (
|
|
33
|
+
RESOURCE_ID_META_KEY,
|
|
34
|
+
RESOURCE_OWNER_META_KEY,
|
|
35
|
+
RESOURCE_REFS_META_KEY,
|
|
36
|
+
process_instance_token,
|
|
37
|
+
)
|
|
38
|
+
from .registry import TypeRegistry, TypeSpec
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class ResidentLookupError(Exception):
|
|
42
|
+
"""A resident stub arrived in a process that does not hold the value."""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def resident_resource_id(rid: str) -> str:
|
|
46
|
+
"""The resident's identity as holders see it: the codec fingerprint,
|
|
47
|
+
the envelope's RESOURCE_ID_META_KEY, and the ID caches invalidate by
|
|
48
|
+
are all this one string."""
|
|
49
|
+
return "resident:" + rid
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class ResidencyTable:
|
|
53
|
+
"""One per holding process: resident id -> live object.
|
|
54
|
+
|
|
55
|
+
Idempotent per object (same object, same id), so fingerprinting and
|
|
56
|
+
payload encoding agree, and re-sending the same value re-uses the id.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
def __init__(self) -> None:
|
|
60
|
+
self._objects: dict[str, object] = {}
|
|
61
|
+
self._ids_by_identity: dict[int, str] = {}
|
|
62
|
+
|
|
63
|
+
def rid_for(self, obj: object) -> str:
|
|
64
|
+
rid = self._ids_by_identity.get(id(obj))
|
|
65
|
+
if rid is None or self._objects.get(rid) is not obj:
|
|
66
|
+
rid = uuid.uuid4().hex
|
|
67
|
+
self._objects[rid] = obj
|
|
68
|
+
self._ids_by_identity[id(obj)] = rid
|
|
69
|
+
return rid
|
|
70
|
+
|
|
71
|
+
def get(self, rid: str) -> object:
|
|
72
|
+
try:
|
|
73
|
+
return self._objects[rid]
|
|
74
|
+
except KeyError:
|
|
75
|
+
raise ResidentLookupError(
|
|
76
|
+
f"resident value {rid!r} is not held by this process; it "
|
|
77
|
+
"belongs to another worker or an earlier worker lifetime"
|
|
78
|
+
) from None
|
|
79
|
+
|
|
80
|
+
def remove(self, rid: str) -> object | None:
|
|
81
|
+
"""Drop the table's strong reference; None when already gone.
|
|
82
|
+
|
|
83
|
+
Only for coordinated release (invalidate references first, then
|
|
84
|
+
remove): a stub for a removed resident raises ResidentLookupError
|
|
85
|
+
from then on.
|
|
86
|
+
"""
|
|
87
|
+
obj = self._objects.pop(rid, None)
|
|
88
|
+
if obj is not None:
|
|
89
|
+
self._ids_by_identity.pop(id(obj), None)
|
|
90
|
+
return obj
|
|
91
|
+
|
|
92
|
+
def __len__(self) -> int:
|
|
93
|
+
return len(self._objects)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
_TABLE = ResidencyTable()
|
|
97
|
+
"""Module-level: the holding process's single default residency table."""
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def resident_owners(obj: object) -> tuple[object, ...]:
|
|
101
|
+
"""The primary resident owner followed by additional referenced owners."""
|
|
102
|
+
primary = cast("object", getattr(obj, "_dinkster_resident_owner", obj))
|
|
103
|
+
refs_value = cast("object", getattr(obj, "_dinkster_resident_refs", ()))
|
|
104
|
+
if not isinstance(refs_value, tuple):
|
|
105
|
+
raise TypeError("_dinkster_resident_refs must be a tuple")
|
|
106
|
+
refs = cast("tuple[object, ...]", refs_value)
|
|
107
|
+
owners: list[object] = []
|
|
108
|
+
identities: set[int] = set()
|
|
109
|
+
for owner in (primary, *refs):
|
|
110
|
+
if owner is None:
|
|
111
|
+
raise TypeError("resident owners must not be None")
|
|
112
|
+
if id(owner) in identities:
|
|
113
|
+
continue
|
|
114
|
+
identities.add(id(owner))
|
|
115
|
+
owners.append(owner)
|
|
116
|
+
return tuple(owners)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class ResidentCodec:
|
|
120
|
+
"""Reusable codec functions for a type that admits resident values."""
|
|
121
|
+
|
|
122
|
+
def __init__(
|
|
123
|
+
self,
|
|
124
|
+
table: ResidencyTable | None = None,
|
|
125
|
+
meta: Callable[[object], Mapping[str, object]] | None = None,
|
|
126
|
+
) -> None:
|
|
127
|
+
self._table = table if table is not None else _TABLE
|
|
128
|
+
self._meta = meta
|
|
129
|
+
|
|
130
|
+
def metadata(self, obj: object) -> Mapping[str, object]:
|
|
131
|
+
owners = resident_owners(obj)
|
|
132
|
+
owner = owners[0]
|
|
133
|
+
enriched: dict[str, object] = dict(self._meta(owner)) if self._meta is not None else {}
|
|
134
|
+
enriched[RESOURCE_ID_META_KEY] = resident_resource_id(self._table.rid_for(owner))
|
|
135
|
+
additional = tuple(
|
|
136
|
+
resident_resource_id(self._table.rid_for(reference)) for reference in owners[1:]
|
|
137
|
+
)
|
|
138
|
+
if additional:
|
|
139
|
+
enriched[RESOURCE_REFS_META_KEY] = additional
|
|
140
|
+
enriched[RESOURCE_OWNER_META_KEY] = process_instance_token()
|
|
141
|
+
return enriched
|
|
142
|
+
|
|
143
|
+
def encode(self, obj: object) -> bytes:
|
|
144
|
+
return json.dumps({"residentId": self._table.rid_for(obj)}).encode("utf-8")
|
|
145
|
+
|
|
146
|
+
def decode(self, data: bytes) -> object:
|
|
147
|
+
wire = cast("dict[str, object]", json.loads(data))
|
|
148
|
+
rid = wire.get("residentId")
|
|
149
|
+
if not isinstance(rid, str):
|
|
150
|
+
raise ResidentLookupError(f"malformed resident stub: {data!r}")
|
|
151
|
+
return self._table.get(rid)
|
|
152
|
+
|
|
153
|
+
def validate_encoded(self, data: bytes) -> None:
|
|
154
|
+
try:
|
|
155
|
+
parsed: object = json.loads(data)
|
|
156
|
+
except (UnicodeDecodeError, json.JSONDecodeError):
|
|
157
|
+
raise ResidentLookupError(f"malformed resident stub: {data!r}") from None
|
|
158
|
+
if not isinstance(parsed, dict):
|
|
159
|
+
raise ResidentLookupError(f"malformed resident stub: {data!r}")
|
|
160
|
+
wire = cast("dict[object, object]", parsed)
|
|
161
|
+
if set(wire) != {"residentId"}:
|
|
162
|
+
raise ResidentLookupError(f"malformed resident stub: {data!r}")
|
|
163
|
+
if not isinstance(wire["residentId"], str) or not wire["residentId"]:
|
|
164
|
+
raise ResidentLookupError(f"malformed resident stub: {data!r}")
|
|
165
|
+
|
|
166
|
+
def fingerprint(self, obj: object) -> str:
|
|
167
|
+
declared = getattr(obj, "_dinkster_resident_fingerprint", None)
|
|
168
|
+
if declared is not None:
|
|
169
|
+
if not isinstance(declared, str) or not declared:
|
|
170
|
+
raise TypeError("_dinkster_resident_fingerprint must be a non-empty string")
|
|
171
|
+
return declared
|
|
172
|
+
return resident_resource_id(self._table.rid_for(obj))
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def register_resident_type(
|
|
176
|
+
registry: TypeRegistry,
|
|
177
|
+
type_id: str,
|
|
178
|
+
table: ResidencyTable | None = None,
|
|
179
|
+
meta: Callable[[object], Mapping[str, object]] | None = None,
|
|
180
|
+
*,
|
|
181
|
+
coerce: Callable[[object], object] | None = None,
|
|
182
|
+
) -> TypeSpec:
|
|
183
|
+
"""``meta`` publishes residency/cost for the live object (device lanes,
|
|
184
|
+
VRAM cost) - it rides the envelope across the boundary even though the
|
|
185
|
+
object itself never does. Every resident envelope additionally carries
|
|
186
|
+
RESOURCE_ID_META_KEY: the value is a *reference* to owner-resolved
|
|
187
|
+
state, so holders exclude its cost from their accounting and can be
|
|
188
|
+
asked to drop entries referencing it (invalidate-then-release)."""
|
|
189
|
+
codec = ResidentCodec(table, meta)
|
|
190
|
+
|
|
191
|
+
spec = registry.register(
|
|
192
|
+
type_id,
|
|
193
|
+
encode=codec.encode,
|
|
194
|
+
decode=codec.decode,
|
|
195
|
+
fingerprint=codec.fingerprint,
|
|
196
|
+
meta=codec.metadata,
|
|
197
|
+
coerce=coerce,
|
|
198
|
+
)
|
|
199
|
+
registry.register_resident_table(table if table is not None else _TABLE)
|
|
200
|
+
return spec
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
__all__ = [
|
|
204
|
+
"ResidencyTable",
|
|
205
|
+
"ResidentCodec",
|
|
206
|
+
"ResidentLookupError",
|
|
207
|
+
"register_resident_type",
|
|
208
|
+
"resident_owners",
|
|
209
|
+
"resident_resource_id",
|
|
210
|
+
]
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
"""ResourceHandle: envelope values for things that cannot cross a wire raw.
|
|
2
|
+
|
|
3
|
+
Models/VAE/CLIP are not data - they are loaded hardware state. A
|
|
4
|
+
ResourceHandle is the envelope-shaped truth about one: a stable identity
|
|
5
|
+
(the basis of cache keys), residency (which concrete devices hold it),
|
|
6
|
+
cost (bytes by residency class, what the MemoryGovernor accounts), and -
|
|
7
|
+
only where the resource actually lives - the runtime object itself.
|
|
8
|
+
|
|
9
|
+
Crossing a boundary carries identity + residency + cost and drops the
|
|
10
|
+
object: the receiving side gets an interrogable, schedulable handle it
|
|
11
|
+
cannot resolve. Placement routes consumers to the owner (or consciously
|
|
12
|
+
transfers); a worker that hits ``require_obj()`` on a non-local handle
|
|
13
|
+
has been mis-scheduled, and the error says so.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import json
|
|
19
|
+
from collections.abc import Mapping
|
|
20
|
+
from dataclasses import dataclass, field
|
|
21
|
+
from typing import cast
|
|
22
|
+
|
|
23
|
+
from .builtin_types import RESOURCE_HANDLE_TYPE
|
|
24
|
+
|
|
25
|
+
# RESOURCE_ID_META_KEY's canonical home is model.py (the traversal helpers
|
|
26
|
+
# in lists.py need it below the registry layer); re-exported here where the
|
|
27
|
+
# resource docs live.
|
|
28
|
+
from .model import (
|
|
29
|
+
RESOURCE_ID_META_KEY,
|
|
30
|
+
RESOURCE_OWNER_META_KEY,
|
|
31
|
+
RESOURCES_META_KEY,
|
|
32
|
+
process_instance_token,
|
|
33
|
+
)
|
|
34
|
+
from .registry import TypeRegistry
|
|
35
|
+
|
|
36
|
+
COST_META_KEY = "cost"
|
|
37
|
+
"""Well-known ValueMeta entry: mapping of residency class -> bytes.
|
|
38
|
+
|
|
39
|
+
Residency classes are ``"ram"``, ``"disk"``, and ``"vram:<device>"``
|
|
40
|
+
(device-qualified, because budgets are per device: ``"vram:cuda:0"``).
|
|
41
|
+
Cost is scheduling/accounting metadata only - never part of the
|
|
42
|
+
fingerprint, for the same reason residency is not: the same computation
|
|
43
|
+
on different hardware is the same computation.
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def unqualified_cost(cost: object) -> dict[str, int]:
|
|
48
|
+
"""Compare codec byte counts independently of remote residency qualifiers."""
|
|
49
|
+
if not isinstance(cost, Mapping):
|
|
50
|
+
raise ValueError("cost must be a residency mapping")
|
|
51
|
+
result: dict[str, int] = {}
|
|
52
|
+
for residency, nbytes in cast("Mapping[object, object]", cost).items():
|
|
53
|
+
if not isinstance(residency, str) or type(nbytes) is not int or nbytes < 0:
|
|
54
|
+
raise ValueError("cost requires residency names and nonnegative integer bytes")
|
|
55
|
+
name = residency.partition("@")[0]
|
|
56
|
+
if name in result:
|
|
57
|
+
raise ValueError("cost contains duplicate unqualified residencies")
|
|
58
|
+
result[name] = nbytes
|
|
59
|
+
return result
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class ResourceError(Exception):
|
|
63
|
+
"""A resource handle was used somewhere its resource does not live."""
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@dataclass(frozen=True)
|
|
67
|
+
class ResourceHandle:
|
|
68
|
+
"""Identity + residency + cost for a non-serializable resource.
|
|
69
|
+
|
|
70
|
+
resource_id is the stable identity: derive it from content identity
|
|
71
|
+
plus load parameters (e.g. ``blake3:<hex>?dtype=fp16``), never from
|
|
72
|
+
id(), paths, or load order - it is the fingerprint, so it decides
|
|
73
|
+
cache hits.
|
|
74
|
+
|
|
75
|
+
residency uses the RESOURCES_META_KEY shape: resource kind -> concrete
|
|
76
|
+
instance id(s), one (``{"gpu": "cuda:1"}``) or a tuple for a resource
|
|
77
|
+
spanning devices (``{"gpu": ("cuda:0", "cuda:1")}``, the multigpu
|
|
78
|
+
case).
|
|
79
|
+
|
|
80
|
+
cost uses the COST_META_KEY shape: residency class -> bytes.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
resource_id: str
|
|
84
|
+
kind: str
|
|
85
|
+
residency: Mapping[str, str | tuple[str, ...]] = field(
|
|
86
|
+
default_factory=dict[str, str | tuple[str, ...]]
|
|
87
|
+
)
|
|
88
|
+
cost: Mapping[str, int] = field(default_factory=dict[str, int])
|
|
89
|
+
obj: object | None = None
|
|
90
|
+
owner: str | None = None
|
|
91
|
+
"""Producer-stamped owner provenance for a NON-LOCAL handle: the
|
|
92
|
+
process-instance token of the worker holding the object, carried so a
|
|
93
|
+
relay re-wrapping this handle preserves provenance it did not create
|
|
94
|
+
(RESOURCE_OWNER_META_KEY). Ignored when the handle is local - the
|
|
95
|
+
holding process always stamps its own live token, never a remembered
|
|
96
|
+
one. None means the producer predates owner stamping."""
|
|
97
|
+
|
|
98
|
+
def __post_init__(self) -> None:
|
|
99
|
+
residency = {
|
|
100
|
+
key: tuple(value) if not isinstance(value, str) else value
|
|
101
|
+
for key, value in self.residency.items()
|
|
102
|
+
}
|
|
103
|
+
# Private copies preserve boundary serialization (mapping proxies
|
|
104
|
+
# are neither JSON serializable nor pickleable).
|
|
105
|
+
object.__setattr__(self, "residency", residency)
|
|
106
|
+
object.__setattr__(self, "cost", dict(self.cost))
|
|
107
|
+
|
|
108
|
+
@property
|
|
109
|
+
def is_local(self) -> bool:
|
|
110
|
+
return self.obj is not None
|
|
111
|
+
|
|
112
|
+
def require_obj(self) -> object:
|
|
113
|
+
if self.obj is None:
|
|
114
|
+
raise ResourceError(
|
|
115
|
+
f"resource {self.resource_id!r} ({self.kind}) is not local to "
|
|
116
|
+
"this worker; the scheduler must route its consumers to the "
|
|
117
|
+
"owner or transfer it explicitly"
|
|
118
|
+
)
|
|
119
|
+
return self.obj
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _encode_handle(obj: object) -> bytes:
|
|
123
|
+
handle = _require_handle(obj)
|
|
124
|
+
wire = {
|
|
125
|
+
"resourceId": handle.resource_id,
|
|
126
|
+
"kind": handle.kind,
|
|
127
|
+
"residency": {
|
|
128
|
+
k: list(v) if isinstance(v, tuple) else v for k, v in handle.residency.items()
|
|
129
|
+
},
|
|
130
|
+
"cost": dict(handle.cost),
|
|
131
|
+
}
|
|
132
|
+
# Owner provenance crosses the wire so the receiving side can keep
|
|
133
|
+
# relaying it: a local handle is owned HERE (stamp this lifetime's
|
|
134
|
+
# token), a non-local one keeps whatever its producer stamped.
|
|
135
|
+
owner = process_instance_token() if handle.is_local else handle.owner
|
|
136
|
+
if owner is not None:
|
|
137
|
+
wire["owner"] = owner
|
|
138
|
+
return json.dumps(wire, sort_keys=True, separators=(",", ":")).encode("utf-8")
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _decode_handle(data: bytes) -> object:
|
|
142
|
+
wire = cast(Mapping[str, object], json.loads(data))
|
|
143
|
+
residency_raw = cast(Mapping[str, object], wire.get("residency") or {})
|
|
144
|
+
residency: dict[str, str | tuple[str, ...]] = {}
|
|
145
|
+
for k, v in residency_raw.items():
|
|
146
|
+
if isinstance(v, list):
|
|
147
|
+
residency[k] = tuple(cast(list[str], v))
|
|
148
|
+
else:
|
|
149
|
+
residency[k] = cast(str, v)
|
|
150
|
+
cost = {
|
|
151
|
+
k: int(cast(int, v)) for k, v in cast(Mapping[str, object], wire.get("cost") or {}).items()
|
|
152
|
+
}
|
|
153
|
+
owner_raw = wire.get("owner")
|
|
154
|
+
return ResourceHandle(
|
|
155
|
+
resource_id=cast(str, wire["resourceId"]),
|
|
156
|
+
kind=cast(str, wire["kind"]),
|
|
157
|
+
residency=residency,
|
|
158
|
+
cost=cost,
|
|
159
|
+
obj=None, # crossing the wire drops locality by construction
|
|
160
|
+
# Carried, not minted: whatever the producing side stamped rides
|
|
161
|
+
# along so a further relay preserves it (malformed means absent).
|
|
162
|
+
owner=owner_raw if isinstance(owner_raw, str) and owner_raw else None,
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _require_handle(obj: object) -> ResourceHandle:
|
|
167
|
+
if not isinstance(obj, ResourceHandle):
|
|
168
|
+
raise TypeError(
|
|
169
|
+
f"{RESOURCE_HANDLE_TYPE} values must be ResourceHandle, got {type(obj).__name__}"
|
|
170
|
+
)
|
|
171
|
+
return obj
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def _handle_meta(obj: object) -> Mapping[str, object]:
|
|
175
|
+
handle = _require_handle(obj)
|
|
176
|
+
meta: dict[str, object] = {
|
|
177
|
+
RESOURCE_ID_META_KEY: handle.resource_id,
|
|
178
|
+
"kind": handle.kind,
|
|
179
|
+
}
|
|
180
|
+
if handle.is_local:
|
|
181
|
+
# Owner provenance is stamped where the object actually lives
|
|
182
|
+
# (RESOURCE_OWNER_META_KEY): the holding process stamps its own
|
|
183
|
+
# live token, never a remembered one.
|
|
184
|
+
meta[RESOURCE_OWNER_META_KEY] = process_instance_token()
|
|
185
|
+
elif handle.owner is not None:
|
|
186
|
+
# A decoded non-local handle relaying through this process keeps
|
|
187
|
+
# whatever owner its producer stamped - rewriting provenance we
|
|
188
|
+
# did not create would misroute dispatch.
|
|
189
|
+
meta[RESOURCE_OWNER_META_KEY] = handle.owner
|
|
190
|
+
if handle.residency:
|
|
191
|
+
meta[RESOURCES_META_KEY] = dict(handle.residency)
|
|
192
|
+
if handle.cost:
|
|
193
|
+
meta[COST_META_KEY] = dict(handle.cost)
|
|
194
|
+
return meta
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _handle_fingerprint(obj: object) -> str:
|
|
198
|
+
# Identity is the declared resource_id alone: residency and cost are
|
|
199
|
+
# scheduling facts, so the same model on another device stays a hit.
|
|
200
|
+
return _require_handle(obj).resource_id
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def register_resource_handle_type(registry: TypeRegistry) -> None:
|
|
204
|
+
registry.register(
|
|
205
|
+
RESOURCE_HANDLE_TYPE,
|
|
206
|
+
encode=_encode_handle,
|
|
207
|
+
decode=_decode_handle,
|
|
208
|
+
fingerprint=_handle_fingerprint,
|
|
209
|
+
meta=_handle_meta,
|
|
210
|
+
)
|