synax-sdk 0.2.0__py3-none-any.whl

synax_sdk/__init__.py

@@ -0,0 +1,42 @@
+"""Synax SDK — Python library for building skills on the Synax agentic platform.
+
+Public API surface. Anything exported here is part of the stable (within a
+minor version) API; anything not exported is internal and may change.
+
+See ``docs/build_plan.md`` for what's wired up at each milestone.
+"""
+
+from synax_sdk.errors import (
+    CapabilityError,
+    ManifestError,
+    SkillDefinitionError,
+    SkillRuntimeError,
+    SkillValidationError,
+    SynaxSDKError,
+)
+from synax_sdk.manifest import Manifest
+from synax_sdk.runtime import Context, Invoker, ctx, logger, metrics, network, secrets
+from synax_sdk.skill import Secret, Skill, SkillDependency, SkillMetadata
+from synax_sdk.version import __version__
+
+__all__ = [
+    "CapabilityError",
+    "Context",
+    "Invoker",
+    "Manifest",
+    "ManifestError",
+    "Secret",
+    "Skill",
+    "SkillDefinitionError",
+    "SkillDependency",
+    "SkillMetadata",
+    "SkillRuntimeError",
+    "SkillValidationError",
+    "SynaxSDKError",
+    "__version__",
+    "ctx",
+    "logger",
+    "metrics",
+    "network",
+    "secrets",
+]

synax_sdk/build.py

@@ -0,0 +1,164 @@
+"""End-to-end build pipeline: derive manifest → validate → package → sign → write.
+
+This module orchestrates every other M4 module. The CLI's
+``synax skill build`` command loads the :class:`Skill` and the project's
+``entry_point`` (via :mod:`synax_skill_cli.utils.project`) and passes
+them in; ``synax_sdk.build`` itself stays independent of the CLI package
+to avoid a circular dependency.
+
+The pipeline:
+
+1. Caller has already loaded a :class:`Skill` and read the project's
+   ``entry_point`` from ``pyproject.toml [tool.synax]``.
+2. Derive an in-memory :class:`Manifest` (M2 logic).
+3. Build the deterministic tar.gz artifact (M4 packaging); pin its
+   ``sha256`` onto ``implementation.hash`` and set ``entry_point``.
+4. Validate the now-populated manifest. Schema-layer and consistency
+   errors are blocking; warnings are surfaced but don't fail the build.
+5. Sign the canonical form with the chosen key (defaults to the store's
+   active key). Append the :class:`Signature` to the manifest.
+6. Write the signed bundle to ``<project_root>/build/`` by default.
+"""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from pathlib import Path
+
+from synax_sdk.errors import BuildError
+from synax_sdk.manifest import Manifest, Signature
+from synax_sdk.packaging import ArtifactResult, build_implementation_artifact
+from synax_sdk.signing import KeyStore
+from synax_sdk.skill import Skill
+from synax_sdk.validation import ValidationError, validate_manifest
+
+DEFAULT_OUTPUT_SUBDIR = "build"
+BUNDLE_SUBDIR = "signed_bundle"
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    """Everything a successful build produced."""
+
+    manifest: Manifest
+    artifact: ArtifactResult
+    signature: Signature
+    output_dir: Path
+    bundle_dir: Path
+    warnings: list[ValidationError]
+
+
+def build(
+    project_root: Path,
+    skill: Skill,
+    *,
+    entry_point: str,
+    key_fingerprint: str | None = None,
+    output_dir: Path | None = None,
+    key_store: KeyStore | None = None,
+) -> BuildResult:
+    """Run the full build pipeline and return the :class:`BuildResult`.
+
+    Args:
+        project_root: the directory whose contents will be packaged.
+        skill: the loaded skill object (caller has already imported it).
+        entry_point: ``module:variable`` import path (becomes
+            ``implementation.entry_point`` in the manifest).
+        key_fingerprint: signing key. Defaults to the key store's active
+            default (``synax keys set-default``).
+        output_dir: where to write build outputs. Defaults to
+            ``<project_root>/build``.
+        key_store: override the key store location (test seam). Defaults
+            to ``~/.synax/keys``.
+
+    Raises:
+        BuildError: if validation fails with blocking errors, or no
+            signing key is available.
+    """
+    project_root = project_root.resolve()
+    output_dir = (output_dir or project_root / DEFAULT_OUTPUT_SUBDIR).resolve()
+    key_store = key_store or KeyStore.default()
+
+    manifest = Manifest.from_skill(skill)
+    manifest.implementation.entry_point = entry_point
+
+    artifact = build_implementation_artifact(
+        project_root,
+        extra_ignore=_build_output_relative_pattern(project_root, output_dir),
+    )
+    manifest.implementation.hash = artifact.sha256
+
+    errors = validate_manifest(manifest)
+    blocking = [e for e in errors if e.kind != "warning"]
+    warnings = [e for e in errors if e.kind == "warning"]
+    if blocking:
+        raise BuildError(
+            f"Manifest failed validation ({len(blocking)} error(s)). "
+            "Fix the issues below and re-run `synax skill build`.",
+            errors=list(blocking),
+        )
+
+    fingerprint = key_fingerprint or key_store.default_fingerprint
+    if fingerprint is None:
+        raise BuildError(
+            "No signing key available. Run `synax keys generate` to create one, "
+            "or pass --key <fingerprint>."
+        )
+    keypair = key_store.load(fingerprint)
+    canonical = manifest.to_canonical_json()
+    signature_b64 = keypair.signer().sign(canonical)
+    signature = Signature(
+        key_fingerprint=fingerprint,
+        signer_type="author",
+        signature=signature_b64,
+        signed_at=datetime.datetime.now(datetime.UTC).isoformat(),
+    )
+    manifest.signatures.append(signature)
+
+    bundle_dir = _write_outputs(output_dir, manifest, artifact, canonical)
+
+    return BuildResult(
+        manifest=manifest,
+        artifact=artifact,
+        signature=signature,
+        output_dir=output_dir,
+        bundle_dir=bundle_dir,
+        warnings=warnings,
+    )
+
+
+def _build_output_relative_pattern(project_root: Path, output_dir: Path) -> list[str] | None:
+    """Return a ``.synax-skillignore``-compatible pattern excluding ``output_dir``.
+
+    Returns ``None`` when ``output_dir`` is outside the project tree (no
+    need to ignore — packaging wouldn't pick it up anyway).
+    """
+    try:
+        rel = output_dir.relative_to(project_root)
+    except ValueError:
+        return None
+    rel_str = rel.as_posix().strip("/")
+    return [f"{rel_str}/"] if rel_str else None
+
+
+def _write_outputs(
+    output_dir: Path,
+    manifest: Manifest,
+    artifact: ArtifactResult,
+    canonical: bytes,
+) -> Path:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    bundle_dir = output_dir / BUNDLE_SUBDIR
+    bundle_dir.mkdir(parents=True, exist_ok=True)
+
+    # Bundle: what gets uploaded to the platform.
+    (bundle_dir / "manifest.yaml").write_text(manifest.to_yaml(), encoding="utf-8")
+    (bundle_dir / "implementation.tar.gz").write_bytes(artifact.tar_gz_bytes)
+
+    # Diagnostic files at the build root.
+    (output_dir / "manifest.yaml").write_text(manifest.to_yaml(), encoding="utf-8")
+    (output_dir / "manifest.json").write_text(manifest.to_json(), encoding="utf-8")
+    (output_dir / "manifest.canonical").write_bytes(canonical)
+
+    return bundle_dir

synax_sdk/errors.py

@@ -0,0 +1,140 @@
+"""Exception hierarchy for the Synax SDK.
+
+All SDK-raised exceptions inherit from :class:`SynaxSDKError`, so users can
+catch every SDK error with one ``except`` clause if desired. More specific
+subclasses are preferred when the error category is known.
+"""
+
+from __future__ import annotations
+
+
+class SynaxSDKError(Exception):
+    """Base class for every exception raised by the Synax SDK."""
+
+
+class SkillDefinitionError(SynaxSDKError):
+    """A :class:`~synax_sdk.skill.Skill` or tool is defined improperly.
+
+    Raised at construction time (in ``Skill.__init__`` or in the
+    ``@skill.tool`` decorator) when the author's code violates the SDK's
+    structural rules — for example an invalid skill name, a tool with an
+    untyped parameter, or a secret that lacks a matching capability.
+
+    These errors are fatal at *build* time. They never propagate to a
+    running skill, because a skill that fails to define cannot be invoked.
+    """
+
+
+class SkillValidationError(SynaxSDKError):
+    """A skill or manifest failed semantic validation.
+
+    Distinct from :class:`SkillDefinitionError`: definition errors are about
+    *shape* (caught while the Python is being loaded), validation errors
+    are about *consistency* across the whole skill — e.g. a manifest whose
+    JSON Schema doesn't match the schema spec.
+    """
+
+
+class ManifestError(SynaxSDKError):
+    """A manifest could not be constructed, serialized, or parsed."""
+
+
+class SkillRuntimeError(SynaxSDKError):
+    """A skill attempted to use the runtime API in a way that failed.
+
+    Common cases:
+
+    * No runtime backend is active (skill imported but not running inside
+      the platform or a :class:`~synax_sdk.testing.MockPlatform`).
+    * The mock backend was active but the requested secret / context
+      wasn't configured before the skill was invoked.
+
+    The message names what was attempted and what to do about it.
+    """
+
+
+class CapabilityError(SynaxSDKError):
+    """A skill attempted a gated operation without the required capability.
+
+    Raised by the runtime API (e.g. :mod:`synax_sdk.runtime.network`) when
+    the skill's runtime-effective capability set — supplied by the platform
+    via the runtime contract, or programmatically via
+    :class:`~synax_sdk.testing.MockPlatform` in tests — does not include
+    the capability needed for the call.
+
+    Attributes:
+        requested: The capability string the call required, in its most
+            specific form (e.g. ``"network:api.github.com:443"`` for a URL
+            with an explicit port).
+        available: The capabilities currently allowed for the invocation.
+            Capability names are not sensitive and are safe to log.
+
+    The error message names the missing capability and lists what *is*
+    allowed, so the skill author can see at a glance what to add.
+    """
+
+    def __init__(
+        self,
+        *,
+        requested: str,
+        available: frozenset[str],
+    ) -> None:
+        self.requested = requested
+        self.available = frozenset(available)
+        listed = ", ".join(sorted(self.available)) if self.available else "(none)"
+        super().__init__(
+            f"Skill did not declare the required capability {requested!r}. "
+            f"Currently allowed: {listed}. "
+            f"Add it to the Skill's capabilities list to enable this operation."
+        )
+
+
+class BuildError(SynaxSDKError):
+    """A build step (load, validate, package, sign, write) failed.
+
+    Aggregates validation errors when validation is the cause; the CLI
+    formats them into a coloured list. Construct via :meth:`with_errors`
+    when carrying a structured list.
+    """
+
+    def __init__(self, message: str, *, errors: list[object] | None = None) -> None:
+        super().__init__(message)
+        self.errors = errors or []
+
+
+class PublishError(SynaxSDKError):
+    """Base class for publishing failures.
+
+    Subclasses distinguish between authentication problems, server-side
+    rejection of the manifest, version conflicts, and network/transient
+    failures so the CLI can render the right message and exit code.
+    """
+
+
+class PublishAuthError(PublishError):
+    """The platform rejected the auth token (HTTP 401/403)."""
+
+
+class PublishValidationError(PublishError):
+    """The platform rejected the manifest (HTTP 400). Typically because the
+    SDK's vendored schema is ahead of or behind the platform's."""
+
+    def __init__(self, message: str, *, details: object | None = None) -> None:
+        super().__init__(message)
+        self.details = details
+
+
+class PublishVersionConflictError(PublishError):
+    """Version already published (HTTP 409). The author must bump the version."""
+
+    def __init__(self, message: str, *, existing_version_id: str | None = None) -> None:
+        super().__init__(message)
+        self.existing_version_id = existing_version_id
+
+
+# Backwards-compatible alias for the original name (without the Error suffix).
+PublishVersionConflict = PublishVersionConflictError
+
+
+class PublishNetworkError(PublishError):
+    """Network failure or persistent 5xx after retries."""

synax_sdk/manifest.py

@@ -0,0 +1,305 @@
+"""Skill manifest dataclasses, the ``from_skill`` factory, and serialization.
+
+A manifest is the YAML/JSON representation of a skill that the platform
+consumes. This module is the SDK's source of truth for the manifest shape;
+the schema it produces must match ``docs/manifest_spec.md``.
+
+At Milestone 2 the manifest is *in-memory only* — no file I/O, no signing,
+no JSON Schema validation. ``Implementation.entry_point`` and
+``Implementation.hash`` are placeholders that later milestones (4: packaging
+& signing) fill in.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import yaml
+
+from synax_sdk import version as _version_module
+from synax_sdk.errors import ManifestError
+from synax_sdk.skill import Secret, Skill, SkillDependency, SkillMetadata
+from synax_sdk.tool import Tool
+
+SCHEMA_VERSION = "1.0"
+
+SignerType = Literal["author", "platform_verifier", "audit", "customer_internal"]
+ImplementationType = Literal["python_code", "manifest_only", "typescript_code"]
+
+
+# ---------------------------------------------------------------------------
+# Sub-dataclasses
+# ---------------------------------------------------------------------------
+@dataclass
+class Implementation:
+    """How the skill is implemented.
+
+    Only ``type`` is required at construction time. ``entry_point`` and
+    ``hash`` are filled in by the build pipeline (Milestone 4).
+    """
+
+    type: ImplementationType = "python_code"
+    entry_point: str | None = None
+    hash: str | None = None
+    runtime_requirements: dict[str, str] | None = None
+
+
+@dataclass
+class ToolManifest:
+    """A tool as it appears in the manifest."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    returns: dict[str, Any] | None = None
+
+    @classmethod
+    def from_tool(cls, tool: Tool) -> ToolManifest:
+        return cls(
+            name=tool.name,
+            description=tool.description,
+            parameters=dict(tool.parameters_schema),
+            returns=dict(tool.returns_schema) if tool.returns_schema is not None else None,
+        )
+
+
+@dataclass
+class SecretManifest:
+    """A secret as it appears in the manifest."""
+
+    name: str
+    type: str
+    description: str
+    scope_required: str | None = None
+
+    @classmethod
+    def from_secret(cls, secret: Secret) -> SecretManifest:
+        return cls(
+            name=secret.name,
+            type=secret.type,
+            description=secret.description,
+            scope_required=secret.scope_required,
+        )
+
+
+@dataclass
+class DependencyManifest:
+    skill: str
+    version: str
+
+    @classmethod
+    def from_dependency(cls, dep: SkillDependency) -> DependencyManifest:
+        return cls(skill=dep.skill, version=dep.version)
+
+
+@dataclass
+class ManifestMetadata:
+    """Manifest-side metadata. Mirrors :class:`SkillMetadata` and adds
+    ``sdk_version`` (populated automatically by ``Manifest.from_skill``)."""
+
+    category: str | None = None
+    tags: list[str] = field(default_factory=list)
+    homepage: str | None = None
+    source: str | None = None
+    documentation: str | None = None
+    license: str | None = None
+    long_description: str | None = None
+    icon_url: str | None = None
+    sdk_version: str | None = None
+
+    @classmethod
+    def from_skill_metadata(
+        cls, meta: SkillMetadata, *, sdk_version: str | None = None
+    ) -> ManifestMetadata:
+        return cls(
+            category=meta.category,
+            tags=list(meta.tags),
+            homepage=meta.homepage,
+            source=meta.source,
+            documentation=meta.documentation,
+            license=meta.license,
+            long_description=meta.long_description,
+            icon_url=meta.icon_url,
+            sdk_version=sdk_version,
+        )
+
+
+@dataclass
+class Signature:
+    key_fingerprint: str
+    signer_type: SignerType
+    signature: str
+    signed_at: str
+
+
+# ---------------------------------------------------------------------------
+# The top-level Manifest
+# ---------------------------------------------------------------------------
+@dataclass
+class Manifest:
+    """The top-level skill manifest.
+
+    Construct via :meth:`Manifest.from_skill` rather than instantiating
+    directly. Serialize via :meth:`to_yaml`, :meth:`to_json`, or
+    :meth:`to_canonical_json` (the bytes used as input to Ed25519 signing).
+    """
+
+    schema_version: str
+    name: str
+    version: str
+    display_name: str
+    description: str
+    implementation: Implementation
+    tools: list[ToolManifest]
+    namespace: str | None = None
+    capabilities: list[str] = field(default_factory=list)
+    execution_location: str = "either"
+    secrets: list[SecretManifest] = field(default_factory=list)
+    dependencies: list[DependencyManifest] = field(default_factory=list)
+    metadata: ManifestMetadata = field(default_factory=ManifestMetadata)
+    signatures: list[Signature] = field(default_factory=list)
+
+    # -----------------------------------------------------------------------
+    @classmethod
+    def from_skill(
+        cls,
+        skill: Skill,
+        *,
+        sdk_version: str | None = None,
+    ) -> Manifest:
+        """Build a Manifest from a :class:`~synax_sdk.skill.Skill`.
+
+        The resulting manifest has ``implementation.entry_point`` and
+        ``implementation.hash`` left as ``None``; the build pipeline
+        (Milestone 4) fills them in once it knows the packaged artifact's
+        module path and hash.
+
+        Args:
+            skill: source of truth.
+            sdk_version: overrides the auto-detected SDK version stamp in
+                ``metadata.sdk_version``. Mostly useful for reproducible
+                tests.
+        """
+        return cls(
+            schema_version=SCHEMA_VERSION,
+            name=skill.name,
+            namespace=skill.namespace,
+            version=skill.version,
+            display_name=skill.display_name,
+            description=skill.description,
+            implementation=Implementation(type="python_code"),
+            tools=[ToolManifest.from_tool(t) for t in skill.tools],
+            capabilities=list(skill.capabilities),
+            execution_location=skill.execution_location,
+            secrets=[SecretManifest.from_secret(s) for s in skill.secrets],
+            dependencies=[DependencyManifest.from_dependency(d) for d in skill.dependencies],
+            metadata=ManifestMetadata.from_skill_metadata(
+                skill.metadata,
+                sdk_version=(
+                    sdk_version if sdk_version is not None else _version_module.__version__
+                ),
+            ),
+            signatures=[],
+        )
+
+    # -----------------------------------------------------------------------
+    # Serialization
+    # -----------------------------------------------------------------------
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain ``dict`` matching ``manifest_spec.md`` field order.
+
+        Empty optional collections, ``None`` scalars, and defaulted values
+        (``execution_location == "either"``) are omitted so the resulting
+        document is concise.
+        """
+        result: dict[str, Any] = {
+            "schema_version": self.schema_version,
+            "name": self.name,
+        }
+        if self.namespace:
+            result["namespace"] = self.namespace
+        result["version"] = self.version
+        result["display_name"] = self.display_name
+        result["description"] = self.description
+        result["implementation"] = _filter_dataclass(self.implementation)
+        result["tools"] = [_filter_dataclass(t) for t in self.tools]
+        if self.capabilities:
+            result["capabilities"] = list(self.capabilities)
+        if self.execution_location != "either":
+            result["execution_location"] = self.execution_location
+        if self.secrets:
+            result["secrets"] = [_filter_dataclass(s) for s in self.secrets]
+        if self.dependencies:
+            result["dependencies"] = [_filter_dataclass(d) for d in self.dependencies]
+        meta = _filter_dataclass(self.metadata)
+        if meta:
+            result["metadata"] = meta
+        if self.signatures:
+            result["signatures"] = [_filter_dataclass(s) for s in self.signatures]
+        return result
+
+    def to_yaml(self) -> str:
+        """Serialize as a YAML document with the spec's field order preserved."""
+        try:
+            return yaml.safe_dump(
+                self.to_dict(),
+                sort_keys=False,
+                default_flow_style=False,
+                allow_unicode=True,
+            )
+        except yaml.YAMLError as exc:  # pragma: no cover - defensive
+            raise ManifestError(f"Failed to serialize manifest to YAML: {exc}") from exc
+
+    def to_json(self, *, indent: int | None = 2) -> str:
+        """Serialize as JSON. Default is indented for human review."""
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def to_canonical_json(self) -> bytes:
+        """Return the canonical signing bytes.
+
+        The canonical form (per ``manifest_spec.md`` §Canonical form for
+        signing):
+
+        1. JSON object representation
+        2. Drop ``signatures`` (signatures sign everything *except* themselves)
+        3. Sort keys recursively
+        4. No whitespace
+        5. UTF-8 encoded
+        """
+        payload = self.to_dict()
+        payload.pop("signatures", None)
+        return json.dumps(
+            payload,
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _filter_dataclass(obj: Any) -> Any:
+    """Convert a dataclass to dict, omitting None and empty list/dict fields.
+
+    Plain ``dict`` instances inside the dataclass (such as a JSON Schema
+    payload) are returned unchanged — we only filter at the dataclass
+    boundary, not inside opaque payloads.
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        result: dict[str, Any] = {}
+        for f in dataclasses.fields(obj):
+            value = getattr(obj, f.name)
+            cleaned = _filter_dataclass(value)
+            if cleaned is None:
+                continue
+            if isinstance(cleaned, list | dict) and len(cleaned) == 0:
+                continue
+            result[f.name] = cleaned
+        return result
+    if isinstance(obj, list):
+        return [_filter_dataclass(item) for item in obj]
+    return obj