paxlet 0.1.1__tar.gz

paxlet-0.1.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: paxlet
+Version: 0.1.1
+Summary: Small, addressable packages of resources and actions for connected systems.
+Author: Paxlet contributors
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# paxlet
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.05-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.0466 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-09-22 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+
+
+**Build small. Connect everything.**
+
+Paxlet Core is a deliberately small contract for packaging **resources and actions** as addressable capabilities.
+
+A Paxlet has a stable identity, a version, clear inputs/outputs, explicit dependencies and requested permissions. A node can resolve it, verify it, run it and produce a receipt.
+
+```text
+URN identity
+    │
+    ▼
+┌──────────── Paxlet ────────────┐
+│ resources                     │
+│ actions                       │
+│ dependencies                  │
+│ permissions                   │
+│ provenance                    │
+└───────────────────────────────┘
+    │
+    ▼
+URI locations → Node → Receipt
+```
+
+## Start in five minutes
+
+Requires Python 3.11+ and no third-party runtime dependencies. You can run it directly after cloning:
+
+```bash
+./bin/paxlet init /tmp/my-first
+./bin/paxlet run /tmp/my-first hello --input '{"name":"Ada"}'
+
+./bin/paxlet verify examples/hello
+./bin/paxlet run examples/hello hello --input '{"name":"Ada"}'
+```
+
+Optional developer install:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+Or address the same capability by identity:
+
+```bash
+./bin/paxlet resolve urn:paxlet:example:hello
+./bin/paxlet run urn:paxlet:example:hello hello --input '{"name":"Ada"}'
+```
+
+Try a science-oriented example:
+
+```bash
+./bin/paxlet run examples/science-fasta-gc analyze --input '{}'
+./bin/paxlet run examples/statistics-mean mean --input '{"values":[1,2,4,8]}'
+```
+
+## CLI
+
+```text
+paxlet init    DIRECTORY
+paxlet verify  PATH|URN
+paxlet inspect PATH|URN
+paxlet resolve URN
+paxlet run     PATH|URN ACTION --input JSON
+paxlet pack    PATH|URN -o package.paxlet.zip
+```
+
+## Why Core is small
+
+Paxlet is not an AI-agent framework. It is the portable unit that larger systems can use.
+
+```text
+Paxlet Core      package + identity + contract
+Paxlet Node      resolution + grants + execution + receipts
+Paxlet Network   registries + peers + distribution
+Taskand          planning + orchestration + adaptive-system showcase
+```
+
+Taskand can demonstrate planners, processes, federation, mesh, Digital Twin, MCP, governance and recovery without making those features mandatory for every Paxlet implementation.
+
+## Repository map
+
+```text
+SPEC.md                 normative Core 0.1 draft
+schemas/                manifest + receipt schemas
+paxlet/                 tiny Python reference runtime
+examples/               five understandable capabilities
+registry/local.json     local URN → URI resolver example
+conformance/            implementation compatibility runner
+docs/                   addressing, security, receipts, layers
+integrations/taskand/    how Taskand fits as the showcase
+```
+
+## Conformance
+
+```bash
+python -m unittest discover -s tests -v
+python conformance/run.py
+```
+
+## Important security note
+
+The reference runtime is intentionally educational. It validates package paths and exposes secrets only after explicit user grant, but it **does not enforce filesystem/network permissions with an OS sandbox**. Production nodes should use containers, VMs or OS policy for enforcement. See `docs/security.md`.
+
+## Status
+
+Core 0.1 is a draft intended to make the idea testable and implementable by independent runtimes. See `ROADMAP.md`.
+
+
+## License
+
+Licensed under Apache-2.0.

paxlet-0.1.1/README.md

@@ -0,0 +1,129 @@
+# paxlet
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.05-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.0466 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-09-22 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+
+
+**Build small. Connect everything.**
+
+Paxlet Core is a deliberately small contract for packaging **resources and actions** as addressable capabilities.
+
+A Paxlet has a stable identity, a version, clear inputs/outputs, explicit dependencies and requested permissions. A node can resolve it, verify it, run it and produce a receipt.
+
+```text
+URN identity
+    │
+    ▼
+┌──────────── Paxlet ────────────┐
+│ resources                     │
+│ actions                       │
+│ dependencies                  │
+│ permissions                   │
+│ provenance                    │
+└───────────────────────────────┘
+    │
+    ▼
+URI locations → Node → Receipt
+```
+
+## Start in five minutes
+
+Requires Python 3.11+ and no third-party runtime dependencies. You can run it directly after cloning:
+
+```bash
+./bin/paxlet init /tmp/my-first
+./bin/paxlet run /tmp/my-first hello --input '{"name":"Ada"}'
+
+./bin/paxlet verify examples/hello
+./bin/paxlet run examples/hello hello --input '{"name":"Ada"}'
+```
+
+Optional developer install:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+Or address the same capability by identity:
+
+```bash
+./bin/paxlet resolve urn:paxlet:example:hello
+./bin/paxlet run urn:paxlet:example:hello hello --input '{"name":"Ada"}'
+```
+
+Try a science-oriented example:
+
+```bash
+./bin/paxlet run examples/science-fasta-gc analyze --input '{}'
+./bin/paxlet run examples/statistics-mean mean --input '{"values":[1,2,4,8]}'
+```
+
+## CLI
+
+```text
+paxlet init    DIRECTORY
+paxlet verify  PATH|URN
+paxlet inspect PATH|URN
+paxlet resolve URN
+paxlet run     PATH|URN ACTION --input JSON
+paxlet pack    PATH|URN -o package.paxlet.zip
+```
+
+## Why Core is small
+
+Paxlet is not an AI-agent framework. It is the portable unit that larger systems can use.
+
+```text
+Paxlet Core      package + identity + contract
+Paxlet Node      resolution + grants + execution + receipts
+Paxlet Network   registries + peers + distribution
+Taskand          planning + orchestration + adaptive-system showcase
+```
+
+Taskand can demonstrate planners, processes, federation, mesh, Digital Twin, MCP, governance and recovery without making those features mandatory for every Paxlet implementation.
+
+## Repository map
+
+```text
+SPEC.md                 normative Core 0.1 draft
+schemas/                manifest + receipt schemas
+paxlet/                 tiny Python reference runtime
+examples/               five understandable capabilities
+registry/local.json     local URN → URI resolver example
+conformance/            implementation compatibility runner
+docs/                   addressing, security, receipts, layers
+integrations/taskand/    how Taskand fits as the showcase
+```
+
+## Conformance
+
+```bash
+python -m unittest discover -s tests -v
+python conformance/run.py
+```
+
+## Important security note
+
+The reference runtime is intentionally educational. It validates package paths and exposes secrets only after explicit user grant, but it **does not enforce filesystem/network permissions with an OS sandbox**. Production nodes should use containers, VMs or OS policy for enforcement. See `docs/security.md`.
+
+## Status
+
+Core 0.1 is a draft intended to make the idea testable and implementable by independent runtimes. See `ROADMAP.md`.
+
+
+## License
+
+Licensed under Apache-2.0.

paxlet-0.1.1/paxlet/__init__.py

@@ -0,0 +1,3 @@
+"""Paxlet Core 0.1 reference runtime."""
+
+__version__ = "0.1.1"

paxlet-0.1.1/paxlet/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

paxlet-0.1.1/paxlet/cli.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .errors import PaxletError
+from .manifest import load_manifest, package_digest, validate_manifest
+from .packing import pack as pack_paxlet
+from .resolver import resolve, resolve_to_path
+from .runtime import run_action
+
+
+def _target(value: str, registry: str | None) -> Path:
+    if value.startswith("urn:paxlet:"):
+        return resolve_to_path(value, registry)
+    return Path(value)
+
+
+def _json(value) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False, sort_keys=True))
+
+
+
+def command_init(args) -> int:
+    target = Path(args.directory).expanduser().resolve()
+    if target.exists() and any(target.iterdir()) and not args.force:
+        raise PaxletError(f"directory is not empty: {target}; use --force to add starter files")
+    target.mkdir(parents=True, exist_ok=True)
+    name = args.name or target.name
+    slug = "".join(ch.lower() if ch.isalnum() else "-" for ch in name).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    urn = args.urn or f"urn:paxlet:local:{slug}"
+    manifest = {
+        "paxlet": "0.1",
+        "identity": {"urn": urn, "name": name, "version": "0.1.0"},
+        "bindings": [],
+        "actions": {
+            "hello": {
+                "description": "Your first Paxlet action.",
+                "runtime": {"type": "python", "entry": "hello.py"},
+                "input": {"type": "object", "properties": {"name": {"type": "string"}}},
+                "output": {"type": "object", "required": ["message"], "properties": {"message": {"type": "string"}}}
+            }
+        },
+        "resources": [],
+        "requires": [],
+        "permissions": {"filesystem": {"read": [], "write": []}, "network": [], "secrets": []},
+        "provenance": {"created_by": "paxlet init"}
+    }
+    manifest_file = target / "paxlet.json"
+    entry_file = target / "hello.py"
+    if not args.force and (manifest_file.exists() or entry_file.exists()):
+        raise PaxletError("starter files already exist; use --force to overwrite them")
+    manifest_file.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    entry_file.write_text(
+        'import json, sys\n'
+        'payload = json.load(sys.stdin)\n'
+        'name = payload.get("name", "world")\n'
+        'print(json.dumps({"message": f"Hello, {name}!"}))\n',
+        encoding="utf-8",
+    )
+    print(target)
+    print(f"next: paxlet run {target} hello --input '{{\"name\":\"Ada\"}}'")
+    return 0
+
+def command_verify(args) -> int:
+    path = _target(args.target, args.registry)
+    manifest_file, manifest = load_manifest(path)
+    result = validate_manifest(manifest_file.parent, manifest)
+    payload = {"ok": result.ok, "errors": result.errors, "warnings": result.warnings}
+    if result.ok:
+        payload["identity"] = manifest["identity"]
+        payload["package_digest"] = package_digest(manifest_file.parent, manifest)
+    if args.json:
+        _json(payload)
+    else:
+        print("✓ valid Paxlet" if result.ok else "✗ invalid Paxlet")
+        for warning in result.warnings:
+            print(f"! {warning}")
+        for error in result.errors:
+            print(f"- {error}")
+        if result.ok:
+            print(f"  {manifest['identity']['urn']} @ {manifest['identity']['version']}")
+            print(f"  {payload['package_digest']}")
+    return 0 if result.ok else 1
+
+
+def command_inspect(args) -> int:
+    path = _target(args.target, args.registry)
+    manifest_file, manifest = load_manifest(path)
+    result = validate_manifest(manifest_file.parent, manifest)
+    payload = {
+        "valid": result.ok,
+        "identity": manifest.get("identity"),
+        "bindings": manifest.get("bindings", []),
+        "actions": sorted(manifest.get("actions", {}).keys()),
+        "resources": manifest.get("resources", []),
+        "requires": manifest.get("requires", []),
+        "permissions": manifest.get("permissions", {}),
+        "package_digest": package_digest(manifest_file.parent, manifest) if result.ok else None,
+        "warnings": result.warnings,
+        "errors": result.errors,
+    }
+    _json(payload)
+    return 0 if result.ok else 1
+
+
+def command_run(args) -> int:
+    path = _target(args.target, args.registry)
+    try:
+        payload = json.loads(args.input)
+    except json.JSONDecodeError as exc:
+        raise PaxletError(f"--input must be valid JSON: {exc}") from exc
+    output, receipt, receipt_path = run_action(
+        path,
+        args.action,
+        payload,
+        allow_secrets=args.allow_secret,
+        write_receipts=not args.no_receipt,
+    )
+    _json(output)
+    if receipt_path:
+        print(f"receipt: {receipt_path}", file=sys.stderr)
+    if args.show_receipt:
+        print(json.dumps(receipt, indent=2, ensure_ascii=False, sort_keys=True), file=sys.stderr)
+    return 0
+
+
+def command_resolve(args) -> int:
+    locations = resolve(args.urn, args.registry)
+    _json({"urn": args.urn, "locations": locations})
+    return 0
+
+
+def command_pack(args) -> int:
+    output = args.output or (Path(args.target).resolve().name + ".paxlet.zip")
+    path = pack_paxlet(_target(args.target, args.registry), output)
+    print(path)
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="paxlet", description="Paxlet Core 0.1 reference CLI")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", help="create a minimal runnable Paxlet")
+    init.add_argument("directory")
+    init.add_argument("--name")
+    init.add_argument("--urn")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=command_init)
+
+    verify = sub.add_parser("verify", help="validate a Paxlet manifest and package")
+    verify.add_argument("target")
+    verify.add_argument("--registry")
+    verify.add_argument("--json", action="store_true")
+    verify.set_defaults(func=command_verify)
+
+    inspect = sub.add_parser("inspect", help="show the public contract of a Paxlet")
+    inspect.add_argument("target")
+    inspect.add_argument("--registry")
+    inspect.set_defaults(func=command_inspect)
+
+    run = sub.add_parser("run", help="execute one action using JSON stdin/stdout protocol")
+    run.add_argument("target")
+    run.add_argument("action")
+    run.add_argument("--input", default="{}")
+    run.add_argument("--registry")
+    run.add_argument("--allow-secret", action="append", default=[])
+    run.add_argument("--no-receipt", action="store_true")
+    run.add_argument("--show-receipt", action="store_true")
+    run.set_defaults(func=command_run)
+
+    resolve_cmd = sub.add_parser("resolve", help="resolve a stable Paxlet URN to locations")
+    resolve_cmd.add_argument("urn")
+    resolve_cmd.add_argument("--registry")
+    resolve_cmd.set_defaults(func=command_resolve)
+
+    pack_cmd = sub.add_parser("pack", help="create a portable .paxlet.zip archive")
+    pack_cmd.add_argument("target")
+    pack_cmd.add_argument("-o", "--output")
+    pack_cmd.add_argument("--registry")
+    pack_cmd.set_defaults(func=command_pack)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except PaxletError as exc:
+        print(f"paxlet: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

paxlet-0.1.1/paxlet/errors.py

@@ -0,0 +1,14 @@
+class PaxletError(Exception):
+    """Base error for the reference runtime."""
+
+
+class ManifestError(PaxletError):
+    """Manifest is missing or invalid."""
+
+
+class ResolutionError(PaxletError):
+    """An identity cannot be resolved to a usable location."""
+
+
+class RuntimeError(PaxletError):
+    """An action could not be executed."""

paxlet-0.1.1/paxlet/manifest.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import ManifestError
+
+MANIFEST_NAME = "paxlet.json"
+CORE_VERSION = "0.1"
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    ok: bool
+    errors: list[str]
+    warnings: list[str]
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def manifest_path(path: str | Path) -> Path:
+    candidate = Path(path).expanduser()
+    if candidate.is_dir():
+        candidate = candidate / MANIFEST_NAME
+    return candidate.resolve()
+
+
+def load_manifest(path: str | Path) -> tuple[Path, dict[str, Any]]:
+    target = manifest_path(path)
+    if not target.exists():
+        raise ManifestError(f"manifest not found: {target}")
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"invalid JSON in {target}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ManifestError("manifest root must be an object")
+    return target, data
+
+
+def safe_path(root: Path, relative: str) -> Path:
+    if not isinstance(relative, str) or not relative or relative.startswith(("/", "\\")):
+        raise ManifestError(f"path must be a non-empty relative path: {relative!r}")
+    resolved_root = root.resolve()
+    resolved = (resolved_root / relative).resolve()
+    try:
+        resolved.relative_to(resolved_root)
+    except ValueError as exc:
+        raise ManifestError(f"path escapes package root: {relative}") from exc
+    return resolved
+
+
+def _validate_schema_fragment(fragment: Any, label: str, errors: list[str]) -> None:
+    if fragment is None:
+        return
+    if not isinstance(fragment, dict):
+        errors.append(f"{label} must be an object")
+        return
+    if "type" in fragment and fragment["type"] not in {"object", "array", "string", "number", "integer", "boolean", "null"}:
+        errors.append(f"{label}.type is not a supported JSON type")
+    if fragment.get("type") == "object" and "properties" in fragment and not isinstance(fragment["properties"], dict):
+        errors.append(f"{label}.properties must be an object")
+    if "required" in fragment and not (isinstance(fragment["required"], list) and all(isinstance(v, str) for v in fragment["required"])):
+        errors.append(f"{label}.required must be an array of strings")
+
+
+def validate_manifest(package_dir: Path, data: dict[str, Any], check_files: bool = True) -> ValidationResult:
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if data.get("paxlet") != CORE_VERSION:
+        errors.append(f"paxlet must be {CORE_VERSION!r}")
+
+    identity = data.get("identity")
+    if not isinstance(identity, dict):
+        errors.append("identity must be an object")
+    else:
+        urn = identity.get("urn")
+        if not isinstance(urn, str) or not urn.startswith("urn:paxlet:"):
+            errors.append("identity.urn must start with 'urn:paxlet:'")
+        for field in ("name", "version"):
+            if not isinstance(identity.get(field), str) or not identity[field].strip():
+                errors.append(f"identity.{field} must be a non-empty string")
+
+    bindings = data.get("bindings", [])
+    if not isinstance(bindings, list) or not all(isinstance(v, str) and ":" in v for v in bindings):
+        errors.append("bindings must be an array of URI strings")
+
+    actions = data.get("actions", {})
+    resources = data.get("resources", [])
+    if not isinstance(actions, dict):
+        errors.append("actions must be an object")
+        actions = {}
+    if not isinstance(resources, list) or not all(isinstance(v, str) for v in resources):
+        errors.append("resources must be an array of relative paths")
+        resources = []
+    if not actions and not resources:
+        errors.append("a Paxlet must contain at least one action or resource")
+
+    for name, action in actions.items():
+        label = f"actions.{name}"
+        if not isinstance(name, str) or not name.strip():
+            errors.append("action names must be non-empty strings")
+            continue
+        if not isinstance(action, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        runtime = action.get("runtime")
+        if not isinstance(runtime, dict):
+            errors.append(f"{label}.runtime must be an object")
+            continue
+        runtime_type = runtime.get("type")
+        if runtime_type not in {"python", "command"}:
+            errors.append(f"{label}.runtime.type must be 'python' or 'command'")
+        if runtime_type == "python":
+            entry = runtime.get("entry")
+            if not isinstance(entry, str):
+                errors.append(f"{label}.runtime.entry must be a relative path")
+            else:
+                try:
+                    path = safe_path(package_dir, entry)
+                    if check_files and not path.is_file():
+                        errors.append(f"{label}.runtime.entry not found: {entry}")
+                except ManifestError as exc:
+                    errors.append(str(exc))
+        if runtime_type == "command":
+            argv = runtime.get("argv")
+            if not isinstance(argv, list) or not argv or not all(isinstance(v, str) for v in argv):
+                errors.append(f"{label}.runtime.argv must be a non-empty string array")
+        _validate_schema_fragment(action.get("input"), f"{label}.input", errors)
+        _validate_schema_fragment(action.get("output"), f"{label}.output", errors)
+
+    for resource in resources:
+        try:
+            path = safe_path(package_dir, resource)
+            if check_files and not path.exists():
+                errors.append(f"resource not found: {resource}")
+        except ManifestError as exc:
+            errors.append(str(exc))
+
+    requires = data.get("requires", [])
+    if not isinstance(requires, list) or not all(isinstance(v, str) and v.startswith("urn:paxlet:") for v in requires):
+        errors.append("requires must be an array of Paxlet URNs")
+
+    permissions = data.get("permissions", {})
+    if not isinstance(permissions, dict):
+        errors.append("permissions must be an object")
+    else:
+        fs = permissions.get("filesystem", {})
+        if not isinstance(fs, dict):
+            errors.append("permissions.filesystem must be an object")
+        else:
+            for mode in ("read", "write"):
+                vals = fs.get(mode, [])
+                if not isinstance(vals, list) or not all(isinstance(v, str) for v in vals):
+                    errors.append(f"permissions.filesystem.{mode} must be an array of strings")
+        for key in ("network", "secrets"):
+            vals = permissions.get(key, [])
+            if not isinstance(vals, list) or not all(isinstance(v, str) for v in vals):
+                errors.append(f"permissions.{key} must be an array of strings")
+
+    provenance = data.get("provenance", {})
+    if provenance is not None and not isinstance(provenance, dict):
+        errors.append("provenance must be an object")
+
+    if permissions.get("network"):
+        warnings.append("reference runtime declares network permissions but does not enforce a network sandbox")
+    if isinstance(permissions.get("filesystem"), dict) and permissions["filesystem"].get("write"):
+        warnings.append("reference runtime declares filesystem write permissions but does not enforce an OS sandbox")
+
+    return ValidationResult(ok=not errors, errors=errors, warnings=warnings)
+
+
+def collect_package_files(package_dir: Path, data: dict[str, Any]) -> list[Path]:
+    root = package_dir.resolve()
+    files: set[Path] = {root / MANIFEST_NAME}
+    for action in data.get("actions", {}).values():
+        runtime = action.get("runtime", {}) if isinstance(action, dict) else {}
+        if runtime.get("type") == "python" and isinstance(runtime.get("entry"), str):
+            files.add(safe_path(root, runtime["entry"]))
+    for relative in data.get("resources", []):
+        path = safe_path(root, relative)
+        if path.is_dir():
+            for child in path.rglob("*"):
+                if child.is_file():
+                    files.add(child.resolve())
+        else:
+            files.add(path)
+    return sorted(files, key=lambda p: p.relative_to(root).as_posix())
+
+
+def package_digest(package_dir: Path, data: dict[str, Any]) -> str:
+    root = package_dir.resolve()
+    digest = hashlib.sha256()
+    for path in collect_package_files(root, data):
+        relative = path.relative_to(root).as_posix().encode("utf-8")
+        digest.update(len(relative).to_bytes(4, "big"))
+        digest.update(relative)
+        content = path.read_bytes()
+        digest.update(len(content).to_bytes(8, "big"))
+        digest.update(content)
+    return "sha256:" + digest.hexdigest()

paxlet-0.1.1/paxlet/packing.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+import zipfile
+from pathlib import Path
+
+from .errors import ManifestError
+from .manifest import collect_package_files, load_manifest, package_digest, validate_manifest
+
+
+def pack(path: str | Path, output: str | Path) -> Path:
+    manifest_file, manifest = load_manifest(path)
+    root = manifest_file.parent
+    result = validate_manifest(root, manifest)
+    if not result.ok:
+        raise ManifestError("cannot pack invalid Paxlet: " + "; ".join(result.errors))
+    out = Path(output).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    metadata = {
+        "format": "paxlet-archive/0.1",
+        "identity": manifest["identity"],
+        "package_digest": package_digest(root, manifest),
+    }
+    with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for file in collect_package_files(root, manifest):
+            zf.write(file, file.relative_to(root).as_posix())
+        info = zipfile.ZipInfo("PAXLET-METADATA.json", date_time=(1980, 1, 1, 0, 0, 0))
+        info.compress_type = zipfile.ZIP_DEFLATED
+        zf.writestr(info, json.dumps(metadata, indent=2, sort_keys=True) + "\n")
+    return out

paxlet-0.1.1/paxlet/receipt.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .manifest import canonical_json
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def value_digest(value: Any) -> str:
+    return "sha256:" + hashlib.sha256(canonical_json(value)).hexdigest()
+
+
+def new_receipt(*, manifest: dict[str, Any], package_digest: str, action: str, payload: Any, started: str, finished: str, exit_code: int, output: Any, secret_names: list[str]) -> dict[str, Any]:
+    identity = manifest["identity"]
+    return {
+        "receipt": "paxlet/0.1",
+        "identity": {"urn": identity["urn"], "version": identity["version"]},
+        "package_digest": package_digest,
+        "action": action,
+        "input_digest": value_digest(payload),
+        "output_digest": value_digest(output) if exit_code == 0 else None,
+        "runtime": "paxlet-python-reference/0.1.0",
+        "node": socket.gethostname(),
+        "started_at": started,
+        "finished_at": finished,
+        "exit_code": exit_code,
+        "granted_secret_names": sorted(secret_names),
+        "output": output,
+    }
+
+
+def write_receipt(package_dir: Path, receipt: dict[str, Any]) -> Path:
+    directory = package_dir / ".paxlet" / "receipts"
+    directory.mkdir(parents=True, exist_ok=True)
+    safe_time = receipt["finished_at"].replace(":", "-").replace(".", "-")
+    path = directory / f"{safe_time}-{receipt['action']}.json"
+    path.write_text(json.dumps(receipt, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return path

paxlet-0.1.1/paxlet/resolver.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from .errors import ResolutionError
+
+DEFAULT_REGISTRY = Path(__file__).resolve().parents[1] / "registry" / "local.json"
+
+
+def load_registry(path: str | Path | None = None) -> tuple[Path, dict]:
+    target = Path(path).expanduser().resolve() if path else DEFAULT_REGISTRY
+    if not target.exists():
+        raise ResolutionError(f"registry not found: {target}")
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ResolutionError(f"invalid registry JSON: {exc}") from exc
+    if data.get("registry") != "paxlet/0.1" or not isinstance(data.get("entries"), dict):
+        raise ResolutionError("unsupported registry format")
+    return target, data
+
+
+def resolve(urn: str, registry_path: str | Path | None = None) -> list[dict]:
+    target, data = load_registry(registry_path)
+    entries = data["entries"].get(urn, [])
+    if not entries:
+        raise ResolutionError(f"URN not found: {urn}")
+    out: list[dict] = []
+    for item in entries:
+        if not isinstance(item, dict) or not isinstance(item.get("uri"), str):
+            continue
+        uri = item["uri"]
+        parsed = urlparse(uri)
+        if parsed.scheme == "file" and not parsed.netloc:
+            raw_path = unquote(parsed.path)
+            p = Path(raw_path)
+            if not p.is_absolute():
+                p = (target.parent / p).resolve()
+            uri = p.as_uri()
+        out.append({**item, "uri": uri})
+    if not out:
+        raise ResolutionError(f"URN has no usable locations: {urn}")
+    return out
+
+
+def uri_to_path(uri: str) -> Path:
+    parsed = urlparse(uri)
+    if parsed.scheme != "file":
+        raise ResolutionError(f"reference runtime can execute only file: locations, got {parsed.scheme or 'no scheme'}")
+    if parsed.netloc not in ("", "localhost"):
+        raise ResolutionError("remote file:// hosts are not supported")
+    return Path(unquote(parsed.path)).resolve()
+
+
+def resolve_to_path(urn: str, registry_path: str | Path | None = None) -> Path:
+    locations = resolve(urn, registry_path)
+    for item in locations:
+        try:
+            return uri_to_path(item["uri"])
+        except ResolutionError:
+            continue
+    raise ResolutionError(f"no executable file: location for {urn}")

paxlet-0.1.1/paxlet/runtime.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from .errors import RuntimeError
+from .manifest import load_manifest, package_digest, validate_manifest
+from .receipt import new_receipt, utc_now, write_receipt
+from .schema import validate_value
+
+SAFE_ENV_KEYS = ["PATH", "HOME", "USER", "LOGNAME", "TMPDIR", "TMP", "TEMP", "SystemRoot", "WINDIR"]
+
+
+def _environment(manifest: dict[str, Any], package_dir: Path, action: str, allow_secrets: list[str]) -> tuple[dict[str, str], list[str]]:
+    env = {key: os.environ[key] for key in SAFE_ENV_KEYS if key in os.environ}
+    declared = set(manifest.get("permissions", {}).get("secrets", []))
+    granted: list[str] = []
+    for name in allow_secrets:
+        if name not in declared:
+            raise RuntimeError(f"secret {name!r} is not declared by the Paxlet")
+        if name not in os.environ:
+            raise RuntimeError(f"secret {name!r} is not present in the current environment")
+        env[name] = os.environ[name]
+        granted.append(name)
+    identity = manifest["identity"]
+    env.update({
+        "PAXLET_URN": identity["urn"],
+        "PAXLET_VERSION": identity["version"],
+        "PAXLET_ACTION": action,
+        "PAXLET_ROOT": str(package_dir),
+    })
+    return env, granted
+
+
+def run_action(path: str | Path, action_name: str, payload: Any, *, allow_secrets: list[str] | None = None, write_receipts: bool = True) -> tuple[Any, dict[str, Any], Path | None]:
+    manifest_file, manifest = load_manifest(path)
+    package_dir = manifest_file.parent
+    result = validate_manifest(package_dir, manifest)
+    if not result.ok:
+        raise RuntimeError("invalid Paxlet: " + "; ".join(result.errors))
+
+    action = manifest.get("actions", {}).get(action_name)
+    if not isinstance(action, dict):
+        raise RuntimeError(f"action not found: {action_name}")
+    validate_value(payload, action.get("input"), "input")
+
+    runtime = action["runtime"]
+    if runtime["type"] == "python":
+        command = [sys.executable, runtime["entry"]]
+    else:
+        command = runtime["argv"]
+
+    env, granted = _environment(manifest, package_dir, action_name, allow_secrets or [])
+    started = utc_now()
+    completed = subprocess.run(
+        command,
+        cwd=package_dir,
+        input=json.dumps(payload, ensure_ascii=False),
+        text=True,
+        capture_output=True,
+        env=env,
+        check=False,
+    )
+    finished = utc_now()
+
+    if completed.returncode != 0:
+        failure = {
+            "error": "action_failed",
+            "message": completed.stderr.strip() or completed.stdout.strip() or f"exit code {completed.returncode}",
+        }
+        receipt = new_receipt(
+            manifest=manifest,
+            package_digest=package_digest(package_dir, manifest),
+            action=action_name,
+            payload=payload,
+            started=started,
+            finished=finished,
+            exit_code=completed.returncode,
+            output=failure,
+            secret_names=granted,
+        )
+        receipt_path = write_receipt(package_dir, receipt) if write_receipts else None
+        raise RuntimeError(f"action failed ({completed.returncode}): {failure['message']}; receipt={receipt_path}")
+
+    try:
+        output = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"action must write exactly one JSON value to stdout; got: {completed.stdout[:200]!r}") from exc
+    validate_value(output, action.get("output"), "output")
+
+    receipt = new_receipt(
+        manifest=manifest,
+        package_digest=package_digest(package_dir, manifest),
+        action=action_name,
+        payload=payload,
+        started=started,
+        finished=finished,
+        exit_code=0,
+        output=output,
+        secret_names=granted,
+    )
+    receipt_path = write_receipt(package_dir, receipt) if write_receipts else None
+    return output, receipt, receipt_path

paxlet-0.1.1/paxlet/schema.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import RuntimeError
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    if expected == "object":
+        return isinstance(value, dict)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "null":
+        return value is None
+    return True
+
+
+def validate_value(value: Any, schema: dict[str, Any] | None, label: str = "value") -> None:
+    """Validate the intentionally small JSON-Schema subset in Core 0.1."""
+    if not schema:
+        return
+    expected = schema.get("type")
+    if expected and not _matches_type(value, expected):
+        raise RuntimeError(f"{label} must be {expected}")
+    if expected == "object" and isinstance(value, dict):
+        required = schema.get("required", [])
+        for key in required:
+            if key not in value:
+                raise RuntimeError(f"{label}.{key} is required")
+        for key, child_schema in schema.get("properties", {}).items():
+            if key in value and isinstance(child_schema, dict):
+                validate_value(value[key], child_schema, f"{label}.{key}")
+    if expected == "array" and isinstance(value, list) and isinstance(schema.get("items"), dict):
+        for index, item in enumerate(value):
+            validate_value(item, schema["items"], f"{label}[{index}]")

paxlet-0.1.1/paxlet.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: paxlet
+Version: 0.1.1
+Summary: Small, addressable packages of resources and actions for connected systems.
+Author: Paxlet contributors
+Author-email: Tom Sapletta <tom@sapletta.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# paxlet
+
+
+## AI Cost Tracking
+
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.1-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.05-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-1.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+
+- 🤖 **LLM usage:** $0.0466 (1 commits)
+- 👤 **Human dev:** ~$100 (1.0h @ $100/h, 30min dedup)
+
+Generated on 2026-09-22 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+
+---
+
+
+
+**Build small. Connect everything.**
+
+Paxlet Core is a deliberately small contract for packaging **resources and actions** as addressable capabilities.
+
+A Paxlet has a stable identity, a version, clear inputs/outputs, explicit dependencies and requested permissions. A node can resolve it, verify it, run it and produce a receipt.
+
+```text
+URN identity
+    │
+    ▼
+┌──────────── Paxlet ────────────┐
+│ resources                     │
+│ actions                       │
+│ dependencies                  │
+│ permissions                   │
+│ provenance                    │
+└───────────────────────────────┘
+    │
+    ▼
+URI locations → Node → Receipt
+```
+
+## Start in five minutes
+
+Requires Python 3.11+ and no third-party runtime dependencies. You can run it directly after cloning:
+
+```bash
+./bin/paxlet init /tmp/my-first
+./bin/paxlet run /tmp/my-first hello --input '{"name":"Ada"}'
+
+./bin/paxlet verify examples/hello
+./bin/paxlet run examples/hello hello --input '{"name":"Ada"}'
+```
+
+Optional developer install:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e .
+```
+
+Or address the same capability by identity:
+
+```bash
+./bin/paxlet resolve urn:paxlet:example:hello
+./bin/paxlet run urn:paxlet:example:hello hello --input '{"name":"Ada"}'
+```
+
+Try a science-oriented example:
+
+```bash
+./bin/paxlet run examples/science-fasta-gc analyze --input '{}'
+./bin/paxlet run examples/statistics-mean mean --input '{"values":[1,2,4,8]}'
+```
+
+## CLI
+
+```text
+paxlet init    DIRECTORY
+paxlet verify  PATH|URN
+paxlet inspect PATH|URN
+paxlet resolve URN
+paxlet run     PATH|URN ACTION --input JSON
+paxlet pack    PATH|URN -o package.paxlet.zip
+```
+
+## Why Core is small
+
+Paxlet is not an AI-agent framework. It is the portable unit that larger systems can use.
+
+```text
+Paxlet Core      package + identity + contract
+Paxlet Node      resolution + grants + execution + receipts
+Paxlet Network   registries + peers + distribution
+Taskand          planning + orchestration + adaptive-system showcase
+```
+
+Taskand can demonstrate planners, processes, federation, mesh, Digital Twin, MCP, governance and recovery without making those features mandatory for every Paxlet implementation.
+
+## Repository map
+
+```text
+SPEC.md                 normative Core 0.1 draft
+schemas/                manifest + receipt schemas
+paxlet/                 tiny Python reference runtime
+examples/               five understandable capabilities
+registry/local.json     local URN → URI resolver example
+conformance/            implementation compatibility runner
+docs/                   addressing, security, receipts, layers
+integrations/taskand/    how Taskand fits as the showcase
+```
+
+## Conformance
+
+```bash
+python -m unittest discover -s tests -v
+python conformance/run.py
+```
+
+## Important security note
+
+The reference runtime is intentionally educational. It validates package paths and exposes secrets only after explicit user grant, but it **does not enforce filesystem/network permissions with an OS sandbox**. Production nodes should use containers, VMs or OS policy for enforcement. See `docs/security.md`.
+
+## Status
+
+Core 0.1 is a draft intended to make the idea testable and implementable by independent runtimes. See `ROADMAP.md`.
+
+
+## License
+
+Licensed under Apache-2.0.

paxlet-0.1.1/paxlet.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+paxlet/__init__.py
+paxlet/__main__.py
+paxlet/cli.py
+paxlet/errors.py
+paxlet/manifest.py
+paxlet/packing.py
+paxlet/receipt.py
+paxlet/resolver.py
+paxlet/runtime.py
+paxlet/schema.py
+paxlet.egg-info/PKG-INFO
+paxlet.egg-info/SOURCES.txt
+paxlet.egg-info/dependency_links.txt
+paxlet.egg-info/entry_points.txt
+paxlet.egg-info/top_level.txt
+tests/test_core.py

paxlet-0.1.1/paxlet.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

paxlet-0.1.1/paxlet.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paxlet = paxlet.cli:main

paxlet-0.1.1/paxlet.egg-info/top_level.txt

@@ -0,0 +1 @@
+paxlet

paxlet-0.1.1/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "paxlet"
+version = "0.1.1"
+description = "Small, addressable packages of resources and actions for connected systems."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "Paxlet contributors"}, {name = "Tom Sapletta",email = "tom@sapletta.com"}]
+dependencies = []
+license = "Apache-2.0"
+
+[project.scripts]
+paxlet = "paxlet.cli:main"
+
+[tool.setuptools]
+packages = ["paxlet"]
+
+[tool.costs]
+# AI Cost tracking configuration
+badge = true
+update_readme = true
+readme_path = "README.md"
+default_model = "openrouter/qwen/qwen3-coder-next"
+analysis_mode = "byok"
+full_history = true
+max_commits = 500
+
+# Cost thresholds for badge colors (USD)
+badge_color_thresholds = { low = 1.0, medium = 5.0, high = 10.0, critical = 50.0 }

paxlet-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

paxlet-0.1.1/tests/test_core.py

@@ -0,0 +1,53 @@
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+from paxlet.errors import ManifestError
+from paxlet.manifest import load_manifest, validate_manifest
+from paxlet.packing import pack
+from paxlet.resolver import resolve_to_path
+from paxlet.runtime import run_action
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class CoreTests(unittest.TestCase):
+    def test_init_creates_runnable_package(self):
+        with tempfile.TemporaryDirectory() as td:
+            target = Path(td) / "first"
+            created = subprocess.run([sys.executable, "-m", "paxlet.cli", "init", str(target)], cwd=ROOT, text=True, capture_output=True)
+            self.assertEqual(created.returncode, 0, created.stderr)
+            output, _, _ = run_action(target, "hello", {"name": "Ada"}, write_receipts=False)
+            self.assertEqual(output["message"], "Hello, Ada!")
+
+    def test_hello_validates(self):
+        mf, data = load_manifest(ROOT / "examples/hello")
+        self.assertTrue(validate_manifest(mf.parent, data).ok)
+
+    def test_path_escape_rejected(self):
+        mf, data = load_manifest(ROOT / "tests/fixtures/invalid-escape")
+        result = validate_manifest(mf.parent, data)
+        self.assertFalse(result.ok)
+        self.assertTrue(any("escapes package root" in e for e in result.errors))
+
+    def test_run_hello_and_receipt(self):
+        output, receipt, _ = run_action(ROOT / "examples/hello", "hello", {"name": "Ada"}, write_receipts=False)
+        self.assertEqual(output, {"message": "Hello, Ada!"})
+        self.assertEqual(receipt["identity"]["urn"], "urn:paxlet:example:hello")
+        self.assertTrue(receipt["package_digest"].startswith("sha256:"))
+
+    def test_resolver(self):
+        path = resolve_to_path("urn:paxlet:science:fasta-gc", ROOT / "registry/local.json")
+        self.assertEqual(path, (ROOT / "examples/science-fasta-gc").resolve())
+
+    def test_pack(self):
+        with tempfile.TemporaryDirectory() as td:
+            out = pack(ROOT / "examples/hello", Path(td) / "hello.paxlet.zip")
+            self.assertTrue(out.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()