arkhai-vms 0.2.0__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.
arkhai_vms/__init__.py ADDED
@@ -0,0 +1,51 @@
1
+ """Shared VM-domain helpers used across buyer and storefront packages."""
2
+
3
+ from arkhai_vms.compute_requirements import (
4
+ DIMENSION_KEYS,
5
+ DISK_GB_DIMENSION,
6
+ GPU_COUNT_DIMENSION,
7
+ RAM_GB_DIMENSION,
8
+ VCPU_COUNT_DIMENSION,
9
+ )
10
+ from arkhai_vms.provision_terms import (
11
+ VM_PROVISION_KIND,
12
+ VmProvisionTerms,
13
+ make_vm_provision_terms,
14
+ normalize_vm_provision_terms,
15
+ provision_compute_resource,
16
+ provision_duration_seconds,
17
+ provision_payload,
18
+ provision_ssh_public_key,
19
+ provision_start_utc,
20
+ )
21
+ from arkhai_vms.schema import (
22
+ VmListing,
23
+ VmMaterialization,
24
+ VmMessage,
25
+ VmReceipt,
26
+ VmResult,
27
+ VmTerms,
28
+ )
29
+
30
+ __all__ = [
31
+ "DIMENSION_KEYS",
32
+ "DISK_GB_DIMENSION",
33
+ "GPU_COUNT_DIMENSION",
34
+ "RAM_GB_DIMENSION",
35
+ "VCPU_COUNT_DIMENSION",
36
+ "VM_PROVISION_KIND",
37
+ "VmListing",
38
+ "VmMaterialization",
39
+ "VmMessage",
40
+ "VmProvisionTerms",
41
+ "VmReceipt",
42
+ "VmResult",
43
+ "VmTerms",
44
+ "make_vm_provision_terms",
45
+ "normalize_vm_provision_terms",
46
+ "provision_compute_resource",
47
+ "provision_duration_seconds",
48
+ "provision_payload",
49
+ "provision_ssh_public_key",
50
+ "provision_start_utc",
51
+ ]
@@ -0,0 +1,25 @@
1
+ """Canonical VM capacity-dimension vocabulary.
2
+
3
+ These names and units are part of the VM domain contract. Translation into a
4
+ specific provisioning playbook belongs to that provider's requirement delegate.
5
+ """
6
+
7
+ GPU_COUNT_DIMENSION = "gpu_count"
8
+ VCPU_COUNT_DIMENSION = "vcpu_count"
9
+ RAM_GB_DIMENSION = "ram_gb"
10
+ DISK_GB_DIMENSION = "disk_gb"
11
+
12
+ DIMENSION_KEYS: tuple[str, ...] = (
13
+ GPU_COUNT_DIMENSION,
14
+ VCPU_COUNT_DIMENSION,
15
+ RAM_GB_DIMENSION,
16
+ DISK_GB_DIMENSION,
17
+ )
18
+
19
+ __all__ = [
20
+ "DIMENSION_KEYS",
21
+ "DISK_GB_DIMENSION",
22
+ "GPU_COUNT_DIMENSION",
23
+ "RAM_GB_DIMENSION",
24
+ "VCPU_COUNT_DIMENSION",
25
+ ]
@@ -0,0 +1,77 @@
1
+ """VM implementation of the core market-domain contract."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from market_core import (
8
+ MARKET_DOMAIN_CONTRACT_VERSION,
9
+ DomainCapability,
10
+ DomainIdentity,
11
+ ImmutableCodecCapability,
12
+ ImmutablePublicationCapability,
13
+ MarketDomainContract,
14
+ )
15
+
16
+ from .provision_terms import VM_PROVISION_KIND
17
+ from .schema import (
18
+ VmListing,
19
+ VmMaterialization,
20
+ VmMessage,
21
+ VmReceipt,
22
+ VmResult,
23
+ VmTerms,
24
+ )
25
+
26
+
27
+ def _normalize_listing(value: Any) -> VmListing:
28
+ return VmListing.model_validate(value)
29
+
30
+
31
+ def _normalize_message(value: Any) -> VmMessage:
32
+ return VmMessage.model_validate(value)
33
+
34
+
35
+ def _normalize_terms(value: Any) -> VmTerms:
36
+ return VmTerms.model_validate(value)
37
+
38
+
39
+ def _normalize_materialization(value: Any) -> VmMaterialization:
40
+ return VmMaterialization.model_validate(value)
41
+
42
+
43
+ def _normalize_receipt(value: Any) -> VmReceipt:
44
+ return VmReceipt.model_validate(value)
45
+
46
+
47
+ def _normalize_result(value: Any) -> VmResult:
48
+ return VmResult.model_validate(value)
49
+
50
+
51
+ def _publication_source(**kwargs: Any) -> Any:
52
+ from .storefront_adapter import vm_publication_adapter
53
+
54
+ return vm_publication_adapter(**kwargs)
55
+
56
+
57
+ VM_MARKET_DOMAIN = MarketDomainContract(
58
+ identity=DomainIdentity(VM_PROVISION_KIND),
59
+ contract_version=MARKET_DOMAIN_CONTRACT_VERSION,
60
+ codecs=ImmutableCodecCapability(
61
+ normalize_listing=_normalize_listing,
62
+ normalize_message=_normalize_message,
63
+ normalize_terms=_normalize_terms,
64
+ normalize_materialization=_normalize_materialization,
65
+ normalize_receipt=_normalize_receipt,
66
+ normalize_result=_normalize_result,
67
+ ),
68
+ declared_capabilities=frozenset({DomainCapability.PUBLICATION}),
69
+ publication=ImmutablePublicationCapability(
70
+ source_factory=_publication_source,
71
+ ),
72
+ )
73
+
74
+
75
+ def market_domain() -> MarketDomainContract:
76
+ """Return the VM market-domain contract."""
77
+ return VM_MARKET_DOMAIN
@@ -0,0 +1,133 @@
1
+ """VM provision-term construction."""
2
+
3
+ from typing import Any, Literal
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field, field_validator
6
+
7
+
8
+ VM_PROVISION_KIND = "compute.v1"
9
+ VM_PROVISION_VERSION = 1
10
+
11
+
12
+ class VmProvisionPayload(BaseModel):
13
+ """Domain-owned payload schema for VM provision envelope version 1."""
14
+
15
+ model_config = ConfigDict(extra="forbid")
16
+
17
+ duration_seconds: int = Field(gt=0)
18
+ ssh_public_key: str = ""
19
+ start_utc: str | None = None
20
+ compute_resource: dict[str, Any] | None = None
21
+
22
+
23
+ class VmProvisionTerms(BaseModel):
24
+ """VM provision envelope with independently versioned payload."""
25
+
26
+ model_config = ConfigDict(extra="forbid")
27
+
28
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
29
+ version: Literal[1] = VM_PROVISION_VERSION
30
+ payload: dict[str, Any]
31
+
32
+ @field_validator("payload")
33
+ @classmethod
34
+ def _validate_payload(cls, value: dict[str, Any]) -> dict[str, Any]:
35
+ return VmProvisionPayload.model_validate(value).model_dump(
36
+ exclude_none=True,
37
+ )
38
+
39
+ @property
40
+ def duration_seconds(self) -> int | None:
41
+ raw = self.payload.get("duration_seconds")
42
+ return int(raw) if raw is not None else None
43
+
44
+ @property
45
+ def start_utc(self) -> str | None:
46
+ raw = self.payload.get("start_utc")
47
+ if raw is None:
48
+ return None
49
+ text = str(raw).strip()
50
+ return text or None
51
+
52
+ @property
53
+ def ssh_public_key(self) -> str:
54
+ raw = self.payload.get("ssh_public_key")
55
+ return raw if isinstance(raw, str) else ""
56
+
57
+ @property
58
+ def compute_resource(self) -> dict[str, Any] | None:
59
+ raw = self.payload.get("compute_resource")
60
+ return raw if isinstance(raw, dict) else None
61
+
62
+
63
+ def make_vm_provision_terms(
64
+ *,
65
+ duration_seconds: int,
66
+ ssh_public_key: str,
67
+ start_utc: str | None = None,
68
+ compute_resource: dict[str, Any] | None = None,
69
+ ) -> VmProvisionTerms:
70
+ payload: dict[str, Any] = {
71
+ "duration_seconds": int(duration_seconds),
72
+ "ssh_public_key": ssh_public_key,
73
+ }
74
+ if start_utc is not None:
75
+ payload["start_utc"] = str(start_utc)
76
+ if compute_resource is not None:
77
+ payload["compute_resource"] = compute_resource
78
+ return VmProvisionTerms(payload=payload)
79
+
80
+ def normalize_vm_provision_terms(terms: Any) -> VmProvisionTerms:
81
+ """Validate a wire envelope, VM payload, or durably decoded VM message."""
82
+
83
+ if isinstance(terms, dict) and "payload" in terms:
84
+ return VmProvisionTerms.model_validate(terms)
85
+ durable = dict(terms) if isinstance(terms, dict) else terms
86
+ if isinstance(durable, dict):
87
+ kind = durable.pop("kind", VM_PROVISION_KIND)
88
+ if kind != VM_PROVISION_KIND:
89
+ raise ValueError("durable VM provision terms have an unsupported kind")
90
+ durable.pop("settlement_selection", None)
91
+ payload = VmProvisionPayload.model_validate(durable).model_dump(exclude_none=True)
92
+ return VmProvisionTerms(payload=payload)
93
+
94
+
95
+ # ---------------------------------------------------------------------------
96
+ # compute.v1 payload accessors
97
+ # ---------------------------------------------------------------------------
98
+ # Wire-received provision terms arrive as the core opaque carrier
99
+ # (market_core.schemas.ProvisionTerms) or a plain dict; the core model
100
+ # does not interpret the payload. These functions are the VM domain's
101
+ # interpretation of the compute.v1 payload shape, accepting any carrier
102
+ # with a ``payload`` attribute or key.
103
+
104
+
105
+ def provision_payload(terms: Any) -> dict[str, Any]:
106
+ if isinstance(terms, dict):
107
+ raw = terms.get("payload")
108
+ else:
109
+ raw = getattr(terms, "payload", None)
110
+ return raw if isinstance(raw, dict) else {}
111
+
112
+
113
+ def provision_duration_seconds(terms: Any) -> int | None:
114
+ raw = provision_payload(terms).get("duration_seconds")
115
+ return int(raw) if raw is not None else None
116
+
117
+
118
+ def provision_start_utc(terms: Any) -> str | None:
119
+ raw = provision_payload(terms).get("start_utc")
120
+ if raw is None:
121
+ return None
122
+ text = str(raw).strip()
123
+ return text or None
124
+
125
+
126
+ def provision_ssh_public_key(terms: Any) -> str:
127
+ raw = provision_payload(terms).get("ssh_public_key")
128
+ return raw if isinstance(raw, str) else ""
129
+
130
+
131
+ def provision_compute_resource(terms: Any) -> dict[str, Any] | None:
132
+ raw = provision_payload(terms).get("compute_resource")
133
+ return raw if isinstance(raw, dict) else None
arkhai_vms/schema.py ADDED
@@ -0,0 +1,170 @@
1
+ """VM market schema names used by core role runtimes."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime
6
+ from typing import Any, Literal
7
+
8
+ from pydantic import BaseModel, Field, model_validator
9
+ from market_core.schemas import SettlementOption, SettlementSelection
10
+
11
+ from .provision_terms import VM_PROVISION_KIND, VmProvisionTerms
12
+
13
+
14
+ class VmListing(BaseModel):
15
+ """VM-domain listing payload carried by a storefront/registry listing."""
16
+
17
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
18
+ offer_resource: dict[str, Any] = Field(
19
+ description="Compute slice payload offered by the seller.",
20
+ )
21
+ accepted_escrows: list[dict[str, Any]] = Field(default_factory=list)
22
+ settlement_options: list[SettlementOption] | None = None
23
+ demands: list[dict[str, Any]] = Field(default_factory=list)
24
+ max_duration_seconds: int | None = Field(default=None, ge=1)
25
+
26
+ @model_validator(mode="before")
27
+ @classmethod
28
+ def _accept_offer_resource_payload(cls, value: Any) -> Any:
29
+ if not isinstance(value, dict):
30
+ return value
31
+ if "offer_resource" in value:
32
+ return value
33
+ return {"offer_resource": value}
34
+
35
+ @model_validator(mode="after")
36
+ def _validate_listing(self) -> "VmListing":
37
+ if not self.offer_resource:
38
+ raise ValueError("offer_resource must be non-empty")
39
+ if "gpu_model" not in self.offer_resource:
40
+ raise ValueError("offer_resource must include gpu_model")
41
+ if "gpu_count" not in self.offer_resource:
42
+ raise ValueError("offer_resource must include gpu_count")
43
+ return self
44
+
45
+
46
+ class VmMessage(BaseModel):
47
+ """VM-domain negotiation message payload."""
48
+
49
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
50
+ duration_seconds: int
51
+ ssh_public_key: str = Field(default="")
52
+ start_utc: str | None = None
53
+ compute_resource: dict[str, Any] | None = None
54
+ settlement_selection: SettlementSelection | None = None
55
+
56
+ @model_validator(mode="before")
57
+ @classmethod
58
+ def _accept_provision_terms(cls, value: Any) -> Any:
59
+ if isinstance(value, VmProvisionTerms):
60
+ envelope = value
61
+ elif isinstance(value, dict) and "payload" in value:
62
+ envelope = VmProvisionTerms.model_validate(value)
63
+ else:
64
+ return value
65
+ payload = dict(envelope.payload)
66
+ payload["kind"] = envelope.kind
67
+ return payload
68
+
69
+
70
+ class VmTerms(BaseModel):
71
+ """Canonical agreed VM terms produced by negotiation."""
72
+
73
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
74
+ duration_seconds: int = Field(ge=1)
75
+ ssh_public_key: str
76
+ start_utc: str | None = None
77
+ compute_resource: dict[str, Any] | None = None
78
+ settlement_selection: SettlementSelection | None = None
79
+ listing_ref: str | None = None
80
+
81
+ @model_validator(mode="before")
82
+ @classmethod
83
+ def _accept_provision_terms(cls, value: Any) -> Any:
84
+ if isinstance(value, VmProvisionTerms):
85
+ envelope = value
86
+ elif isinstance(value, dict) and "payload" in value:
87
+ envelope = VmProvisionTerms.model_validate(value)
88
+ else:
89
+ return value
90
+ payload = dict(envelope.payload)
91
+ payload["kind"] = envelope.kind
92
+ return payload
93
+
94
+ @model_validator(mode="after")
95
+ def _validate_terms(self) -> "VmTerms":
96
+ if not self.ssh_public_key.strip():
97
+ raise ValueError("ssh_public_key must be non-empty")
98
+ return self
99
+
100
+
101
+ class VmMaterialization(BaseModel):
102
+ """Settlement-to-fulfillment handoff for a VM agreement."""
103
+
104
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
105
+ escrow_uid: str
106
+ duration_seconds: int = Field(ge=1)
107
+ ssh_public_key: str
108
+ compute_resource: dict[str, Any] | None = None
109
+ lease_start_utc: datetime | None = None
110
+ lease_end_utc: datetime | None = None
111
+ listing_ref: str | None = None
112
+ settlement_ref: dict[str, Any] | None = None
113
+
114
+ @model_validator(mode="after")
115
+ def _validate_materialization(self) -> "VmMaterialization":
116
+ if not self.escrow_uid.strip():
117
+ raise ValueError("escrow_uid must be non-empty")
118
+ if not self.ssh_public_key.strip():
119
+ raise ValueError("ssh_public_key must be non-empty")
120
+ if (
121
+ self.lease_start_utc is not None
122
+ and self.lease_end_utc is not None
123
+ and self.lease_start_utc >= self.lease_end_utc
124
+ ):
125
+ raise ValueError("lease_start_utc must be before lease_end_utc")
126
+ return self
127
+
128
+
129
+ class VmReceipt(BaseModel):
130
+ """Domain receipt for VM fulfillment/servicing state."""
131
+
132
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
133
+ escrow_uid: str | None = None
134
+ vm_name: str | None = None
135
+ status: str
136
+ lease_start_utc: datetime | None = None
137
+ lease_end_utc: datetime | None = None
138
+ access_ref: dict[str, Any] | None = None
139
+ result_ref: dict[str, Any] | None = None
140
+
141
+ @model_validator(mode="after")
142
+ def _validate_receipt(self) -> "VmReceipt":
143
+ if not self.status.strip():
144
+ raise ValueError("status must be non-empty")
145
+ if (
146
+ self.lease_start_utc is not None
147
+ and self.lease_end_utc is not None
148
+ and self.lease_start_utc >= self.lease_end_utc
149
+ ):
150
+ raise ValueError("lease_start_utc must be before lease_end_utc")
151
+ return self
152
+
153
+
154
+ class VmResult(BaseModel):
155
+ """Result shape for VM provisioning/release executor slots."""
156
+
157
+ kind: Literal["compute.v1"] = VM_PROVISION_KIND
158
+ action: str
159
+ status: str = "success"
160
+ vm_name: str | None = None
161
+ escrow_uid: str | None = None
162
+ details: dict[str, Any] | None = None
163
+
164
+ @model_validator(mode="after")
165
+ def _validate_result(self) -> "VmResult":
166
+ if not self.action.strip():
167
+ raise ValueError("action must be non-empty")
168
+ if not self.status.strip():
169
+ raise ValueError("status must be non-empty")
170
+ return self
@@ -0,0 +1,104 @@
1
+ """VM storefront publication adapter.
2
+
3
+ The VM domain package owns this lightweight adapter because it defines how VM
4
+ publication candidates map into the core storefront publication-source slots.
5
+ Concrete storefront executables still inject local inventory, tracking, close,
6
+ and registry-publish callbacks.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from collections.abc import Callable
12
+ from typing import Any
13
+
14
+ from core_storefront.publication_sources import PublicationSource
15
+
16
+ CandidateCallback = Callable[[str], list[dict[str, Any]]]
17
+ OpenKeysCallback = Callable[[str], set[str]]
18
+ CloseStaleCallback = Callable[[str, str, str | None], list[str]]
19
+ OfferResourceCallback = Callable[[dict[str, Any]], dict[str, Any]]
20
+ RecordPublishedCallback = Callable[[str, dict[str, Any], str], None]
21
+ ReopenExistingCallback = Callable[
22
+ [
23
+ str,
24
+ str,
25
+ dict[str, Any],
26
+ dict[str, Any],
27
+ list[dict[str, Any]],
28
+ list[dict[str, Any]],
29
+ int | None,
30
+ str | None,
31
+ ],
32
+ dict[str, Any] | None,
33
+ ]
34
+
35
+
36
+ def vm_listing_resource_key(
37
+ resource_id: str | None,
38
+ gpu_count: int | str | None,
39
+ ) -> str:
40
+ """Fallback derivation key for one VM GPU slice."""
41
+ return f"{resource_id}:gpus:{int(gpu_count or 1)}"
42
+
43
+
44
+ def vm_candidate_skip_keys(candidate: dict[str, Any]) -> set[str]:
45
+ """Return skip keys that identify one VM publication candidate."""
46
+ keys: set[str] = set()
47
+ resource_key = candidate.get("resource_key") or vm_listing_resource_key(
48
+ candidate.get("resource_id") or candidate.get("pool_id"),
49
+ candidate.get("gpu_count"),
50
+ )
51
+ for value in (
52
+ resource_key,
53
+ candidate.get("legacy_resource_key"),
54
+ candidate.get("resource_id"),
55
+ candidate.get("pool_id"),
56
+ ):
57
+ if value is not None:
58
+ keys.add(str(value))
59
+ return keys
60
+
61
+
62
+ def vm_offer_resource_for_listing(
63
+ candidate: dict[str, Any],
64
+ *,
65
+ interruptible: bool = False,
66
+ ) -> dict[str, Any]:
67
+ """Build the VM-domain listing payload for a publication candidate."""
68
+ offer = {
69
+ "pool_id": candidate.get("pool_id"),
70
+ "gpu_model": candidate["gpu_model"],
71
+ "gpu_count": candidate["gpu_count"],
72
+ "sla": candidate["sla"],
73
+ "region": candidate["region"],
74
+ "virtualization_type": candidate["offering_mode"],
75
+ }
76
+ if candidate.get("resource_id"):
77
+ offer["resource_id"] = candidate["resource_id"]
78
+ if interruptible:
79
+ offer["interruptible"] = True
80
+ offer["settlement_model"] = "splitter_refund"
81
+ return offer
82
+
83
+
84
+ def vm_publication_adapter(
85
+ *,
86
+ open_keys: OpenKeysCallback,
87
+ close_stale: CloseStaleCallback,
88
+ available_candidates: CandidateCallback,
89
+ offer_resource: OfferResourceCallback,
90
+ record_published: RecordPublishedCallback,
91
+ reopen_existing: ReopenExistingCallback,
92
+ ) -> PublicationSource:
93
+ """Build the VM publication source for a concrete storefront."""
94
+ return PublicationSource(
95
+ name="vms",
96
+ open_keys=open_keys,
97
+ close_stale=close_stale,
98
+ available_candidates=available_candidates,
99
+ skip_keys=vm_candidate_skip_keys,
100
+ offer_resource=offer_resource,
101
+ record_published=record_published,
102
+ reopen_existing=reopen_existing,
103
+ reopen_error_label="reopen derived listing",
104
+ )
@@ -0,0 +1,10 @@
1
+ Metadata-Version: 2.5
2
+ Name: arkhai-vms
3
+ Version: 0.2.0
4
+ Summary: Shared VM-domain models and helpers used by Arkhai VM buyer and storefront packages.
5
+ License-Expression: MIT
6
+ Requires-Python: <3.14,>=3.12
7
+ Requires-Dist: arkhai-core>=0.2.0
8
+ Requires-Dist: pydantic>=2
9
+ Provides-Extra: storefront
10
+ Requires-Dist: arkhai-core-storefront>=0.3.0; extra == 'storefront'
@@ -0,0 +1,10 @@
1
+ arkhai_vms/__init__.py,sha256=eRo1gipY9rrIyzy2Fb3YWSv2rJh1tBbAvlaHTyR8o7w,1177
2
+ arkhai_vms/compute_requirements.py,sha256=Vi8PgrIGzRwO2Gq4ORV34mEhhq678pSILmRZMlY9wtg,614
3
+ arkhai_vms/domain_runtime.py,sha256=pM1e5493k_W2SfQ9JJxVY6C_PfEhv2Zu_I2tgHhjMcw,1985
4
+ arkhai_vms/provision_terms.py,sha256=RJTrgAXPgqZ6qSQZ84DLLsDcpj5NBs5PPUeG6zO-G_8,4416
5
+ arkhai_vms/schema.py,sha256=tpedwjFF9OckqBUYLJXjtcDWIiP89FQj1h_HvG3Xu8s,5952
6
+ arkhai_vms/storefront_adapter.py,sha256=TOh1tLHdXQT4sPqqbrj2Cma6vVVVz9dzgPLLXmMaXFk,3322
7
+ arkhai_vms-0.2.0.dist-info/METADATA,sha256=F_nKY4YiJywrY08x4lfqxXpagWo3W1XOIL6Naylu7gE,358
8
+ arkhai_vms-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
9
+ arkhai_vms-0.2.0.dist-info/entry_points.txt,sha256=VydTkl1Vsf4qUyf2vzz9F5_uh6-0S8YC8-vuQy-4yxg,77
10
+ arkhai_vms-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.32.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [market.storefront_domains]
2
+ vms = arkhai_vms.domain_runtime:VM_MARKET_DOMAIN