charms-core 0.1.0__py3-none-any.whl

charms_core/__init__.py

@@ -0,0 +1,112 @@
+"""charms-core — shared contracts for the Charms platform."""
+
+from charms_core import protocol
+from charms_core.chunk import Chunk, decode_chunk_message, encode_chunk_message
+from charms_core.node import BasicNode, ConfigT, InputT, OutputT
+from charms_core.package import (
+    EnvVarSpec,
+    OptionType,
+    PriceUnit,
+    PyprojectInfo,
+    SeedInstallSpec,
+    SeedOption,
+    SeedPackage,
+    SeedPackageManifest,
+    SeedPrice,
+    load_seed_package,
+    validate_environment,
+)
+from charms_core.recipe import (
+    Binding,
+    Bindings,
+    CatalogEntry,
+    FieldValue,
+    NodeCatalog,
+    Recipe,
+    RecipeEdge,
+    RecipeNode,
+    ValidationProblem,
+    chunk_path,
+    topo_sort,
+    validate_recipe,
+)
+from charms_core.seed import (
+    ArtifactDownloader,
+    Seed,
+    SeedArtifact,
+    SeedContext,
+    SeedDescriptor,
+    SeedManifest,
+    SeedResources,
+)
+from charms_core.types import (
+    CharmsError,
+    ConfigurationError,
+    IncompatiblePortError,
+    InsufficientManaError,
+    Modality,
+    NodeExecutionError,
+    NodeMetadata,
+    NoRuneAvailableError,
+    PortSchema,
+    ProtocolError,
+    RecipeValidationError,
+    SeedPackageError,
+    TaskFailedError,
+    modalities_compatible,
+)
+
+__all__ = [
+    "ArtifactDownloader",
+    "BasicNode",
+    "Binding",
+    "Bindings",
+    "CatalogEntry",
+    "CharmsError",
+    "Chunk",
+    "ConfigT",
+    "ConfigurationError",
+    "EnvVarSpec",
+    "FieldValue",
+    "IncompatiblePortError",
+    "InputT",
+    "InsufficientManaError",
+    "Modality",
+    "NodeCatalog",
+    "NodeExecutionError",
+    "NodeMetadata",
+    "NoRuneAvailableError",
+    "OptionType",
+    "OutputT",
+    "PortSchema",
+    "PriceUnit",
+    "ProtocolError",
+    "PyprojectInfo",
+    "Recipe",
+    "RecipeEdge",
+    "RecipeNode",
+    "RecipeValidationError",
+    "Seed",
+    "SeedArtifact",
+    "SeedContext",
+    "SeedDescriptor",
+    "SeedInstallSpec",
+    "SeedManifest",
+    "SeedOption",
+    "SeedPackage",
+    "SeedPackageError",
+    "SeedPackageManifest",
+    "SeedPrice",
+    "SeedResources",
+    "TaskFailedError",
+    "ValidationProblem",
+    "chunk_path",
+    "decode_chunk_message",
+    "encode_chunk_message",
+    "load_seed_package",
+    "modalities_compatible",
+    "protocol",
+    "topo_sort",
+    "validate_environment",
+    "validate_recipe",
+]

charms_core/chunk.py

@@ -0,0 +1,81 @@
+"""
+The streaming unit and its wire codec.
+
+A ``Chunk`` travels over WebSockets as one JSON text frame; if it carries a
+binary payload the JSON includes ``"binary": true`` and **exactly one** binary
+frame with the raw bytes follows immediately on the same connection. Text
+chunks embed their payload inline and send no binary frame. This module is the
+only place that framing rule is implemented — both the launcher and client
+sockets reuse it.
+
+Audio payloads are PCM float32 little-endian mono unless ``meta`` says
+otherwise; ``meta.sample_rate`` is mandatory for audio chunks.
+"""
+
+import json
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+from charms_core.types import Modality, ProtocolError
+
+
+class Chunk(BaseModel):
+    """One unit of a realtime stream."""
+
+    stream_id: str
+    seq: int = Field(ge=0, description="0-based sequence number within the stream")
+    timestamp_ms: float = 0.0
+    is_final: bool = False  # final marker; may carry a zero-length payload
+    modality: Modality
+    text: str | None = None  # TEXT chunks: payload travels inline in the JSON
+    data: bytes | None = Field(default=None, exclude=True)  # binary payload, never in JSON
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _check_payload(self) -> "Chunk":
+        if self.text is not None and self.data is not None:
+            raise ValueError("a chunk carries either inline text or binary data, not both")
+        if self.text is not None and self.modality is not Modality.TEXT:
+            raise ValueError("inline text payload requires modality=text")
+        if (
+            self.modality is Modality.AUDIO
+            and self.data is not None
+            and "sample_rate" not in self.meta
+        ):
+            raise ValueError("audio chunks must declare meta.sample_rate")
+        return self
+
+
+def encode_chunk_message(message_type: str, chunk: Chunk) -> tuple[str, bytes | None]:
+    """
+    Encode a chunk as a wire message.
+
+    Returns ``(json_text, binary_payload)``; when the payload is not None the
+    sender MUST transmit it as the next binary frame on the same connection.
+    """
+    payload = chunk.model_dump(mode="json")
+    payload["type"] = message_type
+    payload["binary"] = chunk.data is not None
+    return json.dumps(payload), chunk.data
+
+
+def decode_chunk_message(obj: dict[str, Any], binary: bytes | None) -> Chunk:
+    """
+    Decode a parsed chunk-message JSON object plus its (optional) binary frame.
+
+    Raises ProtocolError when framing is broken (a declared binary frame is
+    missing, an undeclared one is supplied, or the fields don't validate).
+    """
+    expects_binary = bool(obj.get("binary", False))
+    if expects_binary and binary is None:
+        raise ProtocolError("chunk message declared a binary frame but none was supplied")
+    if not expects_binary and binary is not None:
+        raise ProtocolError("binary frame supplied for a chunk message that declared none")
+    fields = {k: v for k, v in obj.items() if k not in ("type", "binary")}
+    if binary is not None:
+        fields["data"] = binary
+    try:
+        return Chunk.model_validate(fields)
+    except ValidationError as exc:
+        raise ProtocolError(f"invalid chunk message: {exc}") from exc

charms_core/node.py

@@ -0,0 +1,91 @@
+"""
+BasicNode — the server-executed recipe node.
+
+Basic nodes are strictly lightweight glue (the heavy-compute principle):
+no GPU, no model runtimes, no heavy imports, no blocking I/O. Anything
+heavier is a Seed executed remotely by a Rune.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from charms_core.chunk import Chunk
+from charms_core.types import (
+    IncompatiblePortError,
+    NodeMetadata,
+    PortSchema,
+    modalities_compatible,
+)
+
+InputT = TypeVar("InputT", bound=BaseModel)
+OutputT = TypeVar("OutputT", bound=BaseModel)
+ConfigT = TypeVar("ConfigT", bound="BaseModel | None")
+
+
+class BasicNode(ABC, Generic[InputT, OutputT, ConfigT]):
+    """
+    Atomic in-process processing unit.
+
+    Generic parameters
+    ------------------
+    InputT  — Pydantic model for data inputs
+    OutputT — Pydantic model for data outputs
+    ConfigT — Pydantic model for configuration (use ``None`` if not needed)
+
+    Conventions: ``run()`` never reads env vars or files; errors at the node
+    boundary are ``CharmsError`` subclasses; ``Field(description=...)`` doubles
+    as the UI tooltip and ``json_schema_extra`` carries UI hints.
+    """
+
+    input_model: ClassVar[type[BaseModel]]
+    output_model: ClassVar[type[BaseModel]]
+    config_model: ClassVar[type[BaseModel] | None] = None
+    supports_streaming: ClassVar[bool] = False  # if True, implement transform_chunk()
+
+    @classmethod
+    @abstractmethod
+    def metadata(cls) -> NodeMetadata:
+        """Return static metadata describing this node's ports."""
+
+    @abstractmethod
+    async def run(self, input: InputT, config: ConfigT | None = None) -> OutputT:
+        """Execute this node's logic and return an output."""
+
+    async def transform_chunk(self, chunk: Chunk) -> Chunk | None:
+        """
+        Per-chunk transform for streaming-capable basic nodes on a realtime
+        chunk path. Return None to swallow a chunk.
+        """
+        raise NotImplementedError(f"{type(self).__name__} does not support streaming")
+
+    # ------------------------------------------------------------------ #
+    #  Port / compatibility helpers                                        #
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def input_ports(cls) -> list[PortSchema]:
+        return cls.metadata().inputs
+
+    @classmethod
+    def output_ports(cls) -> list[PortSchema]:
+        return cls.metadata().outputs
+
+    @classmethod
+    def accepts(cls, port: PortSchema) -> bool:
+        """Return True if this node has an input port compatible with *port*."""
+        return any(modalities_compatible(port.modality, inp.modality) for inp in cls.input_ports())
+
+    @classmethod
+    def assert_compatible(cls, upstream: "type[BasicNode[Any, Any, Any]]") -> None:
+        """
+        Raise IncompatiblePortError if no output port of *upstream* matches any
+        input port of this node.
+        """
+        for out_port in upstream.output_ports():
+            if cls.accepts(out_port):
+                return
+        raise IncompatiblePortError(
+            f"No compatible connection: {upstream.metadata().node_id} → {cls.metadata().node_id}"
+        )

charms_core/package.py

@@ -0,0 +1,345 @@
+"""
+The seed package format.
+
+A seed package is the distributable form of a Seed — the zip archive users
+import into, and export from, the platform's seed registry (docker analogy:
+the pushed image). At the archive root it must contain:
+
+- ``manifest.json``  — a :class:`SeedPackageManifest`: the seed node's options
+  schema (drives UI widgets), the price, and environment-variable rules.
+- ``pyproject.toml`` — packaging metadata (name, description, authors,
+  dependencies) and the ``charms.seeds`` entry point.
+- ``README.md``      — documentation rendered in the catalog.
+- the Python code (conventionally ``src/<package>/``) implementing the Seed.
+
+``load_seed_package`` validates all of that without importing any seed code.
+"""
+
+import io
+import json
+import re
+import zipfile
+from collections.abc import Mapping
+from enum import Enum
+
+import tomllib
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+from charms_core.seed import SeedResources
+from charms_core.types import SeedPackageError
+
+MANIFEST_FILENAME = "manifest.json"
+PYPROJECT_FILENAME = "pyproject.toml"
+README_FILENAME = "README.md"
+SEED_ENTRY_POINT_GROUP = "charms.seeds"
+
+_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+_ENV_NAME_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+class OptionType(str, Enum):
+    """
+    The value type of a seed-node option; determines how the option renders
+    in the UI (boolean → switch, enum → dropdown, integer/float → number
+    input with min/max, char → length-limited text input, …).
+    """
+
+    TEXT = "text"
+    BOOLEAN = "boolean"
+    INTEGER = "integer"
+    FLOAT = "float"
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    CHAR = "char"  # length-limited string; requires `length`
+    ENUM = "enum"  # predefined list of choices; requires `choices`
+
+
+class SeedOption(BaseModel):
+    """One entry of the seed node's options schema (mirrors a Config field)."""
+
+    name: str = Field(description="snake_case option name, matching the Config model field")
+    type: OptionType
+    label: str = ""
+    description: str = ""
+    required: bool = False
+    default: str | int | float | bool | None = None
+    min: float | None = Field(default=None, description="integer/float only")
+    max: float | None = Field(default=None, description="integer/float only")
+    length: int | None = Field(default=None, ge=1, description="char only: maximum length")
+    choices: list[str] | None = Field(default=None, description="enum only: allowed values")
+
+    @model_validator(mode="after")
+    def _check_constraints(self) -> "SeedOption":
+        if not _ID_RE.match(self.name):
+            raise ValueError(f"option name {self.name!r} must be snake_case")
+        numeric = self.type in (OptionType.INTEGER, OptionType.FLOAT)
+        if (self.min is not None or self.max is not None) and not numeric:
+            raise ValueError(f"option {self.name!r}: min/max only apply to integer/float")
+        if self.min is not None and self.max is not None and self.min > self.max:
+            raise ValueError(f"option {self.name!r}: min must be <= max")
+        if self.type is OptionType.CHAR and self.length is None:
+            raise ValueError(f"option {self.name!r}: char options require `length`")
+        if self.length is not None and self.type is not OptionType.CHAR:
+            raise ValueError(f"option {self.name!r}: `length` only applies to char")
+        if self.type is OptionType.ENUM and not self.choices:
+            raise ValueError(f"option {self.name!r}: enum options require non-empty `choices`")
+        if self.choices is not None and self.type is not OptionType.ENUM:
+            raise ValueError(f"option {self.name!r}: `choices` only applies to enum")
+        return self
+
+
+class PriceUnit(str, Enum):
+    """
+    How the seed's price is denominated. Billing currently meters
+    ``mana_per_second`` (compute time); other units are stored and shown in
+    the catalog so seeds can declare them ahead of metering support.
+    """
+
+    MANA_PER_SECOND = "mana_per_second"
+    MANA_PER_TOKEN = "mana_per_token"
+    MANA_PER_REQUEST = "mana_per_request"
+
+
+class SeedPrice(BaseModel):
+    """What running this seed costs."""
+
+    value: float = Field(default=1.0, ge=0)
+    unit: PriceUnit = PriceUnit.MANA_PER_SECOND
+
+
+class EnvVarSpec(BaseModel):
+    """
+    An environment variable the seed reads, with validation rules the
+    launcher enforces before starting a Rune.
+    """
+
+    name: str = Field(description="UPPER_SNAKE_CASE variable name")
+    description: str = ""
+    required: bool = False
+    secret: bool = False  # UI renders the value masked
+    default: str | None = None
+    pattern: str | None = Field(default=None, description="regex the value must fully match")
+
+    @model_validator(mode="after")
+    def _check(self) -> "EnvVarSpec":
+        if not _ENV_NAME_RE.match(self.name):
+            raise ValueError(f"environment variable name {self.name!r} must be UPPER_SNAKE_CASE")
+        if self.pattern is not None:
+            try:
+                re.compile(self.pattern)
+            except re.error as exc:
+                raise ValueError(
+                    f"environment variable {self.name!r}: invalid pattern: {exc}"
+                ) from exc
+        return self
+
+
+class SeedInstallSpec(BaseModel):
+    """
+    Package-index configuration for installing the seed's dependencies into
+    its isolated environment. ``index_packages`` pins named requirements to a
+    specific index, installed in their own exclusive step — the reliable way
+    to get CUDA torch builds (``{"torch":
+    "https://download.pytorch.org/whl/cu128"}``): with a mere extra index,
+    a newer PyPI release outranks the CUDA wheels.
+    """
+
+    index_url: str | None = Field(default=None, description="replaces PyPI entirely")
+    extra_index_urls: list[str] = Field(
+        default_factory=list, description="searched in addition to PyPI"
+    )
+    index_packages: dict[str, str] = Field(
+        default_factory=dict,
+        description="package name → index URL; installed first, from that index only",
+    )
+
+    @model_validator(mode="after")
+    def _check(self) -> "SeedInstallSpec":
+        for url in [self.index_url, *self.extra_index_urls, *self.index_packages.values()]:
+            if url is not None and not url.startswith(("http://", "https://")):
+                raise ValueError(f"package index {url!r} must be an http(s) URL")
+        return self
+
+
+class SeedPackageManifest(BaseModel):
+    """The ``manifest.json`` document at the root of every seed package."""
+
+    schema_version: int = 1
+    id: str = Field(description="snake_case, globally unique, e.g. 'echo', 'whisper'")
+    name: str
+    version: str = "0.1.0"
+    description: str = ""
+    supports_dispatch: bool = True
+    supports_streaming: bool = False
+    options: list[SeedOption] = Field(default_factory=list)
+    price: SeedPrice = Field(default_factory=SeedPrice)
+    environment: list[EnvVarSpec] = Field(default_factory=list)
+    resources: SeedResources = Field(default_factory=SeedResources)
+    install: SeedInstallSpec = Field(default_factory=SeedInstallSpec)
+
+    @model_validator(mode="after")
+    def _check(self) -> "SeedPackageManifest":
+        if self.schema_version != 1:
+            raise ValueError(f"unsupported manifest schema_version {self.schema_version}")
+        if not _ID_RE.match(self.id):
+            raise ValueError(f"seed id {self.id!r} must be snake_case")
+        names = [option.name for option in self.options]
+        if len(names) != len(set(names)):
+            raise ValueError("option names must be unique")
+        env_names = [spec.name for spec in self.environment]
+        if len(env_names) != len(set(env_names)):
+            raise ValueError("environment variable names must be unique")
+        return self
+
+
+class PyprojectInfo(BaseModel):
+    """Packaging metadata extracted from the package's ``pyproject.toml``."""
+
+    name: str
+    version: str
+    description: str = ""
+    authors: list[str] = Field(default_factory=list)
+    dependencies: list[str] = Field(default_factory=list)
+    entry_point: str | None = None  # "<module>:<Class>" for the charms.seeds entry
+
+
+class SeedPackage(BaseModel):
+    """A parsed, validated seed package (metadata only — never executes code)."""
+
+    manifest: SeedPackageManifest
+    pyproject: PyprojectInfo
+    readme: str
+
+
+def validate_environment(manifest: SeedPackageManifest, env: Mapping[str, str]) -> list[str]:
+    """
+    Check *env* against the manifest's environment rules; returns a list of
+    human-readable problems (empty when everything passes).
+    """
+    problems: list[str] = []
+    for spec in manifest.environment:
+        value = env.get(spec.name, spec.default)
+        if value is None or value == "":
+            if spec.required:
+                hint = f": {spec.description}" if spec.description else ""
+                problems.append(f"{spec.name} is required{hint}")
+            continue
+        if spec.pattern is not None and re.fullmatch(spec.pattern, value) is None:
+            problems.append(f"{spec.name} does not match pattern {spec.pattern!r}")
+    return problems
+
+
+def _parse_pyproject(text: str, manifest: SeedPackageManifest) -> PyprojectInfo:
+    try:
+        document = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise SeedPackageError(f"pyproject.toml is not valid TOML: {exc}") from exc
+    project = document.get("project")
+    if not isinstance(project, dict):
+        raise SeedPackageError("pyproject.toml has no [project] table")
+    name = project.get("name")
+    version = project.get("version")
+    if not isinstance(name, str) or not isinstance(version, str):
+        raise SeedPackageError("pyproject.toml [project] must declare name and version")
+    authors: list[str] = []
+    for author in project.get("authors", []):
+        if isinstance(author, dict):
+            label = str(author.get("name", "")).strip()
+            email = str(author.get("email", "")).strip()
+            if label and email:
+                authors.append(f"{label} <{email}>")
+            elif label or email:
+                authors.append(label or email)
+    dependencies = [dep for dep in project.get("dependencies", []) if isinstance(dep, str)]
+    entry_points = project.get("entry-points", {})
+    seed_entries = (
+        entry_points.get(SEED_ENTRY_POINT_GROUP, {}) if isinstance(entry_points, dict) else {}
+    )
+    entry_point = seed_entries.get(manifest.id) if isinstance(seed_entries, dict) else None
+    if not isinstance(entry_point, str):
+        raise SeedPackageError(
+            f'pyproject.toml must declare [project.entry-points."{SEED_ENTRY_POINT_GROUP}"] '
+            f'{manifest.id} = "<module>:<SeedClass>"'
+        )
+    return PyprojectInfo(
+        name=name,
+        version=version,
+        description=str(project.get("description", "")),
+        authors=authors,
+        dependencies=dependencies,
+        entry_point=entry_point,
+    )
+
+
+def _archive_root(names: list[str]) -> str:
+    """
+    Packages may be zipped either from inside the seed directory (files at the
+    archive root) or as the directory itself (one shared top-level folder).
+    Returns the prefix ("" or "<folder>/") under which the package files live.
+    """
+    if MANIFEST_FILENAME in names:
+        return ""
+    tops = {name.split("/", 1)[0] for name in names if name.strip("/")}
+    if len(tops) == 1:
+        prefix = f"{next(iter(tops))}/"
+        if f"{prefix}{MANIFEST_FILENAME}" in names:
+            return prefix
+    raise SeedPackageError(f"{MANIFEST_FILENAME} is missing from the package root")
+
+
+def _read_text(archive: zipfile.ZipFile, name: str) -> str:
+    try:
+        data = archive.read(name)
+    except KeyError:
+        raise SeedPackageError(f"{name} is missing from the package") from None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise SeedPackageError(f"{name} is not valid UTF-8") from exc
+
+
+def load_seed_package(data: bytes) -> SeedPackage:
+    """
+    Parse and validate a seed package archive. Raises :class:`SeedPackageError`
+    with a user-facing message on any structural problem. Never imports or
+    executes packaged code.
+    """
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(data))
+    except zipfile.BadZipFile as exc:
+        raise SeedPackageError("not a valid zip archive") from exc
+    with archive:
+        names = archive.namelist()
+        for member in names:
+            normalized = member.replace("\\", "/")
+            if normalized.startswith("/") or ".." in normalized.split("/"):
+                raise SeedPackageError(f"unsafe path in archive: {member!r}")
+        root = _archive_root([name.replace("\\", "/") for name in names])
+
+        raw_manifest = _read_text(archive, f"{root}{MANIFEST_FILENAME}")
+        try:
+            manifest = SeedPackageManifest.model_validate(json.loads(raw_manifest))
+        except json.JSONDecodeError as exc:
+            raise SeedPackageError(f"{MANIFEST_FILENAME} is not valid JSON: {exc}") from exc
+        except ValidationError as exc:
+            first = exc.errors()[0]
+            location = ".".join(str(part) for part in first["loc"])
+            detail = f" ({location})" if location else ""
+            raise SeedPackageError(
+                f"{MANIFEST_FILENAME} is invalid{detail}: {first['msg']}"
+            ) from exc
+
+        pyproject = _parse_pyproject(_read_text(archive, f"{root}{PYPROJECT_FILENAME}"), manifest)
+        if pyproject.version != manifest.version:
+            raise SeedPackageError(
+                f"version mismatch: manifest.json says {manifest.version}, "
+                f"pyproject.toml says {pyproject.version}"
+            )
+        readme = _read_text(archive, f"{root}{README_FILENAME}")
+        has_python = any(
+            name.replace("\\", "/").startswith(root) and name.endswith(".py") for name in names
+        )
+        if not has_python:
+            raise SeedPackageError("the package contains no Python code (*.py)")
+    return SeedPackage(manifest=manifest, pyproject=pyproject, readme=readme)