swarmkit-schema 1.0.0__tar.gz

swarmkit_schema-1.0.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+.eggs/
+*.egg-info/
+*.egg
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# Node / TypeScript
+node_modules/
+.next/
+out/
+.turbo/
+.nx/
+dist/
+*.tsbuildinfo
+.pnpm-store/
+.yarn/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+*~
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+*.pem
+
+# SwarmKit runtime artifacts (per design §9.3)
+.swarmkit/
+*.sqlite
+*.sqlite-journal
+
+# Claude Code
+.claude/settings.local.json
+
+# Build / logs
+*.log
+.cache/
+_site/

swarmkit_schema-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: swarmkit-schema
+Version: 1.0.0
+Summary: SwarmKit JSON Schemas + Python validator.
+Author: Srijith Kartha
+License: MIT
+Keywords: json-schema,schema,swarmkit
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: referencing>=0.35
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-jsonschema; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+SwarmKit canonical JSON Schemas + Python validator. See https://github.com/delivstat/swarmkit

swarmkit_schema-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "swarmkit-schema"
+version = "1.0.0"
+description = "SwarmKit JSON Schemas + Python validator."
+readme = {text = "SwarmKit canonical JSON Schemas + Python validator. See https://github.com/delivstat/swarmkit", content-type = "text/markdown"}
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Srijith Kartha" }]
+keywords = ["swarmkit", "schema", "json-schema"]
+
+dependencies = [
+    "jsonschema>=4.23",
+    "pydantic>=2.8",
+    "pyyaml>=6.0",
+    "referencing>=0.35",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "mypy>=1.11",
+    "ruff>=0.6",
+    "types-pyyaml",
+    "types-jsonschema",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/swarmkit_schema"]

swarmkit_schema-1.0.0/src/swarmkit_schema/__init__.py

@@ -0,0 +1,56 @@
+"""SwarmKit schema validators (Python).
+
+The JSON Schema files under `packages/schema/schemas/` are the source of truth —
+this package only validates against them. See `packages/schema/CLAUDE.md` for
+the dual-surface rule.
+
+Resolution order:
+  1. `_schemas/` inside the installed package (wheel builds via hatch
+     `force-include`).
+  2. `packages/schema/schemas/` relative to this file (editable / dev mode).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+import jsonschema
+
+__version__ = "0.0.1"
+
+SchemaName = Literal["topology", "skill", "archetype", "workspace", "trigger"]
+
+_HERE = Path(__file__).resolve().parent
+
+
+def _schema_root() -> Path:
+    installed = _HERE / "_schemas"
+    if installed.is_dir():
+        return installed
+    # Editable dev mode: packages/schema/python/src/swarmkit_schema → ../../../schemas
+    dev = _HERE.parent.parent.parent / "schemas"
+    if dev.is_dir():
+        return dev
+    raise RuntimeError(f"Canonical JSON Schemas not found. Looked in:\n  {installed}\n  {dev}")
+
+
+def _load(name: SchemaName) -> dict[str, Any]:
+    path = _schema_root() / f"{name}.schema.json"
+    data: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    return data
+
+
+def get_schema(name: SchemaName) -> dict[str, Any]:
+    """Return the canonical JSON Schema for the given artifact type."""
+    return _load(name)
+
+
+def validate(name: SchemaName, instance: Any) -> None:
+    """Validate `instance` against the named schema. Raises `ValidationError` on failure."""
+    schema = _load(name)
+    jsonschema.validate(instance=instance, schema=schema)
+
+
+__all__ = ["SchemaName", "__version__", "get_schema", "validate"]

swarmkit_schema-1.0.0/src/swarmkit_schema/_schemas/archetype.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.swarmkit.dev/v1/archetype.schema.json",
+  "title": "SwarmKit Archetype",
+  "description": "A kind of agent (noun). See design §6.6, §13 and design/details/archetype-schema-v1.md.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "role", "defaults", "provenance"],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": { "const": "swarmkit/v1" },
+    "kind": { "const": "Archetype" },
+    "metadata": { "$ref": "#/$defs/metadata" },
+    "role": {
+      "enum": ["root", "leader", "worker"],
+      "description": "Must match the agent role where this archetype is instantiated."
+    },
+    "defaults": { "$ref": "#/$defs/defaults" },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "description"],
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 10 }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": { "$ref": "#/$defs/model" },
+        "prompt": { "$ref": "#/$defs/prompt" },
+        "skills": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/skill_entry" }
+        },
+        "iam": { "$ref": "#/$defs/iam" }
+      }
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "provider": { "type": "string" },
+        "name": { "type": "string" },
+        "temperature": { "type": "number", "minimum": 0, "maximum": 2 },
+        "max_tokens": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "prompt": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "system": { "type": "string" },
+        "persona": { "type": "string" }
+      }
+    },
+    "skill_entry": {
+      "$comment": "Concrete skill ID (string) or abstract-skill placeholder (§6.6 edge case).",
+      "oneOf": [
+        { "$ref": "#/$defs/identifier" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["abstract"],
+          "properties": {
+            "abstract": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["category"],
+              "properties": {
+                "category": {
+                  "enum": ["capability", "decision", "coordination", "persistence"]
+                },
+                "capability": {
+                  "type": "string",
+                  "description": "Free-text tag matched by the topology resolver."
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "iam": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "base_scope": { "type": "array", "items": { "type": "string" } },
+        "elevated_scopes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authored_by", "version"],
+      "properties": {
+        "authored_by": {
+          "enum": [
+            "human",
+            "authored_by_swarm",
+            "derived_from_template",
+            "imported_from_registry",
+            "vendor_published"
+          ]
+        },
+        "authored_date": { "type": "string", "format": "date" },
+        "version": { "$ref": "#/$defs/semver" },
+        "registry": { "type": "string" },
+        "vendor": { "type": "string" }
+      }
+    }
+  }
+}

swarmkit_schema-1.0.0/src/swarmkit_schema/_schemas/skill.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.swarmkit.dev/v1/skill.schema.json",
+  "title": "SwarmKit Skill",
+  "description": "A discrete capability an agent can exercise. See design §6 and design/details/skill-schema-v1.md.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "category", "implementation", "provenance"],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": { "const": "swarmkit/v1" },
+    "kind": { "const": "Skill" },
+    "metadata": { "$ref": "#/$defs/metadata" },
+    "category": {
+      "enum": ["capability", "decision", "coordination", "persistence"],
+      "description": "Runtime semantics differ by category (design §6.2)."
+    },
+    "inputs": {
+      "type": "object",
+      "description": "JSON Schema (draft 2020-12) defining the skill's input shape.",
+      "additionalProperties": true
+    },
+    "outputs": {
+      "type": "object",
+      "description": "JSON Schema defining the skill's output shape. Passed to providers for structured generation (Tier 0) and used for deterministic validation (Tier 1). See design/details/structured-output-governance.md.",
+      "additionalProperties": true
+    },
+    "implementation": { "$ref": "#/$defs/implementation" },
+    "iam": { "$ref": "#/$defs/iam" },
+    "constraints": { "$ref": "#/$defs/constraints" },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "allOf": [
+    {
+      "$comment": "Decision skills must emit a human-readable reasoning string so audits and reviews have a rationale alongside the verdict. See design/details/skill-schema-v1.md §'Decision-category output contract'.",
+      "if": {
+        "properties": { "category": { "const": "decision" } },
+        "required": ["category"]
+      },
+      "then": {
+        "required": ["outputs"],
+        "properties": {
+          "outputs": {
+            "required": ["properties"],
+            "properties": {
+              "properties": {
+                "required": ["reasoning"]
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "iam_scope": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]*:[a-z*][a-z0-9_*-]*$",
+      "description": "namespace:action — e.g. repo:read, github:write, skills:activate, mcp_servers:*"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "description"],
+      "properties": {
+        "id": { "$ref": "#/$defs/identifier" },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 10 }
+      }
+    },
+    "fields": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/field" }
+    },
+    "field": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": ["string", "number", "integer", "boolean", "enum", "object", "array"]
+        },
+        "required": { "type": "boolean" },
+        "description": { "type": "string" },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required when type=enum."
+        },
+        "range": {
+          "type": "array",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2,
+          "description": "[min, max] — only for number/integer."
+        },
+        "items": {
+          "$ref": "#/$defs/field",
+          "description": "Required when type=array."
+        },
+        "properties": {
+          "$ref": "#/$defs/fields",
+          "description": "Optional when type=object."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "enum" } }, "required": ["type"] },
+          "then": { "required": ["values"] }
+        },
+        {
+          "if": { "properties": { "type": { "const": "array" } }, "required": ["type"] },
+          "then": { "required": ["items"] }
+        }
+      ]
+    },
+    "implementation": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "server", "tool"],
+          "properties": {
+            "type": { "const": "mcp_tool" },
+            "server": { "type": "string", "minLength": 1 },
+            "tool": { "type": "string", "minLength": 1 },
+            "arguments": { "type": "object" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "prompt"],
+          "properties": {
+            "type": { "const": "llm_prompt" },
+            "model": { "type": "object", "additionalProperties": true },
+            "prompt": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "composes"],
+          "properties": {
+            "type": { "const": "composed" },
+            "composes": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/identifier" }
+            },
+            "strategy": {
+              "enum": ["parallel-consensus", "sequential", "custom"]
+            }
+          }
+        }
+      ]
+    },
+    "iam": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "required_scopes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/iam_scope" }
+        }
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_latency_ms": { "type": "integer", "minimum": 1 },
+        "timeout_seconds": { "type": "integer", "minimum": 1 },
+        "retry": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "attempts": { "type": "integer", "minimum": 0 },
+            "backoff": { "enum": ["exponential", "linear", "none"] }
+          }
+        },
+        "on_failure": { "enum": ["escalate_to_human", "fail", "retry", "fallback"] }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authored_by", "version"],
+      "properties": {
+        "authored_by": {
+          "enum": [
+            "human",
+            "authored_by_swarm",
+            "derived_from_template",
+            "imported_from_registry",
+            "vendor_published"
+          ]
+        },
+        "authored_date": { "type": "string", "format": "date" },
+        "version": { "$ref": "#/$defs/semver" },
+        "registry": { "type": "string" },
+        "vendor": { "type": "string" }
+      }
+    }
+  }
+}