arkitekt-spec 1.0.0__tar.gz

arkitekt_spec-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage

arkitekt_spec-1.0.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.5
+Name: arkitekt-spec
+Version: 1.0.0
+Summary: the wire format of an Arkitekt app: manifest, requirements, inspection, hardware selectors and deployments.yaml
+Author-email: jhnnsrs <jhnnsrs@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# arkitekt-spec
+
+The wire format of an Arkitekt app: one definition of *what an app is*, shared by everything
+that produces or consumes it.
+
+| Model | What it is | Produced by | Consumed by |
+| --- | --- | --- | --- |
+| `AppManifest`, `Requirement` | who the app is, which services it needs | arkitekt (from the `App`) | kabinet |
+| `Inspection` | what the app declares (rekuest's action language, carried as JSON) | `arkitekt inspect all`, inside the image | arkitekt's plugin CLI, kabinet |
+| `Selector` (`cpu`, `ram`, `cuda`, `rocm`, `oneapi`, `label`) | where a flavour may run | a flavour's `config.yaml` | kabinet, deployers |
+| `DeploymentsFile` | `.arkitekt/deployments.yaml`, the images a repo publishes | `arkitekt plugin publish` | kabinet's repo scan |
+
+It depends only on pydantic and pyyaml. It deliberately does **not** depend on rekuest: the
+implementations, states, locks and bloks inside an inspection are rekuest's language, and each
+side validates them with its own rekuest models.
+
+## Compatibility
+
+Every envelope model **ignores** unknown keys. An inspection is written by the arkitekt inside
+an image and read by the host CLI, and `deployments.yaml` is written by the CLI and read by a
+kabinet server that upgrades on its own schedule. Adding a field is therefore a minor change
+an older reader survives. A change an older reader must refuse bumps `spec_version`.
+
+Selectors are the exception: they refuse unknown keys, because they are written by hand and a
+typo must not silently widen a placement constraint.
+
+```python
+from arkitekt_spec import load_deployments, dump_deployments
+
+file = load_deployments(open(".arkitekt/deployments.yaml").read())
+```
+
+`python -m arkitekt_spec` prints the JSON Schema. The committed snapshot in
+`tests/fixtures/deployments.schema.json` makes every format change show up in review.

arkitekt_spec-1.0.0/README.md

@@ -0,0 +1,34 @@
+# arkitekt-spec
+
+The wire format of an Arkitekt app: one definition of *what an app is*, shared by everything
+that produces or consumes it.
+
+| Model | What it is | Produced by | Consumed by |
+| --- | --- | --- | --- |
+| `AppManifest`, `Requirement` | who the app is, which services it needs | arkitekt (from the `App`) | kabinet |
+| `Inspection` | what the app declares (rekuest's action language, carried as JSON) | `arkitekt inspect all`, inside the image | arkitekt's plugin CLI, kabinet |
+| `Selector` (`cpu`, `ram`, `cuda`, `rocm`, `oneapi`, `label`) | where a flavour may run | a flavour's `config.yaml` | kabinet, deployers |
+| `DeploymentsFile` | `.arkitekt/deployments.yaml`, the images a repo publishes | `arkitekt plugin publish` | kabinet's repo scan |
+
+It depends only on pydantic and pyyaml. It deliberately does **not** depend on rekuest: the
+implementations, states, locks and bloks inside an inspection are rekuest's language, and each
+side validates them with its own rekuest models.
+
+## Compatibility
+
+Every envelope model **ignores** unknown keys. An inspection is written by the arkitekt inside
+an image and read by the host CLI, and `deployments.yaml` is written by the CLI and read by a
+kabinet server that upgrades on its own schedule. Adding a field is therefore a minor change
+an older reader survives. A change an older reader must refuse bumps `spec_version`.
+
+Selectors are the exception: they refuse unknown keys, because they are written by hand and a
+typo must not silently widen a placement constraint.
+
+```python
+from arkitekt_spec import load_deployments, dump_deployments
+
+file = load_deployments(open(".arkitekt/deployments.yaml").read())
+```
+
+`python -m arkitekt_spec` prints the JSON Schema. The committed snapshot in
+`tests/fixtures/deployments.schema.json` makes every format change show up in review.

arkitekt_spec-1.0.0/arkitekt_spec/__init__.py

@@ -0,0 +1,83 @@
+"""The wire format of an Arkitekt app.
+
+One definition of what an app is, shared by everything that produces or consumes it:
+arkitekt's plugin CLI writes it, and the kabinet server reads it.
+
+- :class:`AppManifest` and :class:`Requirement`: who the app is, what services it needs.
+- :class:`Inspection`: what the app declares, in the action language of :mod:`.actions`.
+- :data:`Selector`: where a flavour of it may run.
+- :class:`DeploymentsFile`: ``.arkitekt/deployments.yaml``, the images a repo publishes.
+"""
+
+from typing import Any
+
+from pydantic import TypeAdapter
+
+from arkitekt_spec import actions
+from arkitekt_spec.actions import definition_hash
+from arkitekt_spec.deployment import (
+    DEPLOYMENTS_PATH,
+    SPEC_VERSION,
+    AppImage,
+    DeploymentsFile,
+    DockerImage,
+    dump_deployments,
+    load_deployments,
+)
+from arkitekt_spec.inspection import Inspection
+from arkitekt_spec.manifest import (
+    DEFAULT_ENTRYPOINT,
+    UNKNOWN_AUTHOR,
+    AppManifest,
+    Requirement,
+)
+from arkitekt_spec.selectors import (
+    SELECTOR_KINDS,
+    BaseSelector,
+    CpuSelector,
+    CudaSelector,
+    LabelSelector,
+    OneApiSelector,
+    RamSelector,
+    RocmSelector,
+    Selector,
+)
+
+
+def json_schema() -> dict[str, Any]:
+    """The JSON Schema of ``deployments.yaml`` (and, within it, of every other model)."""
+    return DeploymentsFile.model_json_schema(by_alias=True)
+
+
+def selector_adapter() -> TypeAdapter[Selector]:
+    """A validator for a single selector, dispatched on ``kind``."""
+    return TypeAdapter(Selector)
+
+
+__all__ = [
+    "DEFAULT_ENTRYPOINT",
+    "DEPLOYMENTS_PATH",
+    "SELECTOR_KINDS",
+    "SPEC_VERSION",
+    "UNKNOWN_AUTHOR",
+    "AppImage",
+    "AppManifest",
+    "BaseSelector",
+    "CpuSelector",
+    "CudaSelector",
+    "DeploymentsFile",
+    "DockerImage",
+    "Inspection",
+    "LabelSelector",
+    "OneApiSelector",
+    "RamSelector",
+    "Requirement",
+    "RocmSelector",
+    "Selector",
+    "actions",
+    "definition_hash",
+    "dump_deployments",
+    "json_schema",
+    "load_deployments",
+    "selector_adapter",
+]

arkitekt_spec-1.0.0/arkitekt_spec/__main__.py

@@ -0,0 +1,7 @@
+"""Print the JSON Schema of ``deployments.yaml``: ``python -m arkitekt_spec``."""
+
+import json
+
+from arkitekt_spec import json_schema
+
+print(json.dumps(json_schema(), indent=2, sort_keys=True))