charms-core 0.1.0__tar.gz

charms_core-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Node
+node_modules/
+web/dist/
+
+# Runtime state
+*.db
+*.db-journal
+.env
+logs/
+.rune_pids
+seed_store/
+
+# Model artifacts / caches
+seed-cache/
+checkpoints/
+*.db-shm
+*.db-wal

charms_core-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: charms-core
+Version: 0.1.0
+Summary: Charms shared contracts: node & seed SDK, recipes, chunks, wire protocol, seed packages
+Project-URL: Repository, https://github.com/ArioAtlas/charms-launcher
+Author: ArioAtlas
+Keywords: ai,charms,distributed-computing,sdk,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# charms-core
+
+Shared contracts for the **Charms** platform — a community-powered AI
+workflow system where users design **Charms** (node-graph **Recipes**) and
+run them on a distributed fleet of **Runes**: instances of model-loading
+**Seeds** contributed by users who share their compute and earn **Mana**.
+
+This package is the dependency-light foundation both the Charms server and
+the [charms-launcher](https://github.com/ArioAtlas/charms-launcher) build
+on. Pure Pydantic v2 models plus stdlib — no web framework, no database, no
+model runtimes.
+
+## What's inside
+
+| Module | Contents |
+|---|---|
+| `charms_core.types` | Modalities, port schemas, node metadata, the `CharmsError` hierarchy |
+| `charms_core.node` | `BasicNode` — the in-process glue-node SDK |
+| `charms_core.seed` | `Seed` — the model-module SDK (`load()` / `run()` / streaming trio), manifests, descriptors |
+| `charms_core.package` | The seed package format: `manifest.json` models (typed options, prices, env rules, install indexes) + zip validation |
+| `charms_core.recipe` | Recipe graph models, validation, topological sort |
+| `charms_core.chunk` | The streaming chunk model + binary framing codec |
+| `charms_core.protocol` | Every WebSocket message on the launcher and realtime-client wires |
+
+## Install
+
+```bash
+pip install charms-core
+```
+
+Python ≥ 3.12. Fully typed (`py.typed`).
+
+## Building a Seed
+
+```python
+from pydantic import BaseModel
+from charms_core.seed import Seed, SeedContext, SeedManifest
+from charms_core.types import Modality, PortSchema
+
+class EchoInput(BaseModel):
+    text: str
+
+class EchoOutput(BaseModel):
+    text: str
+
+class EchoSeed(Seed[EchoInput, EchoOutput, None]):
+    manifest = SeedManifest(id="echo", name="Echo")
+    inputs = [PortSchema(name="text", modality=Modality.TEXT)]
+    outputs = [PortSchema(name="text", modality=Modality.TEXT)]
+    input_model = EchoInput
+    output_model = EchoOutput
+
+    async def load(self, ctx: SeedContext) -> None: ...
+
+    async def run(self, input: EchoInput, config: None = None) -> EchoOutput:
+        return EchoOutput(text=input.text)
+```
+
+Package it (with a `manifest.json`, `pyproject.toml`, and `README.md`) and
+import it into a Charms server's seed registry; contributors then pull and
+run it as a Rune via the launcher.

charms_core-0.1.0/README.md

@@ -0,0 +1,61 @@
+# charms-core
+
+Shared contracts for the **Charms** platform — a community-powered AI
+workflow system where users design **Charms** (node-graph **Recipes**) and
+run them on a distributed fleet of **Runes**: instances of model-loading
+**Seeds** contributed by users who share their compute and earn **Mana**.
+
+This package is the dependency-light foundation both the Charms server and
+the [charms-launcher](https://github.com/ArioAtlas/charms-launcher) build
+on. Pure Pydantic v2 models plus stdlib — no web framework, no database, no
+model runtimes.
+
+## What's inside
+
+| Module | Contents |
+|---|---|
+| `charms_core.types` | Modalities, port schemas, node metadata, the `CharmsError` hierarchy |
+| `charms_core.node` | `BasicNode` — the in-process glue-node SDK |
+| `charms_core.seed` | `Seed` — the model-module SDK (`load()` / `run()` / streaming trio), manifests, descriptors |
+| `charms_core.package` | The seed package format: `manifest.json` models (typed options, prices, env rules, install indexes) + zip validation |
+| `charms_core.recipe` | Recipe graph models, validation, topological sort |
+| `charms_core.chunk` | The streaming chunk model + binary framing codec |
+| `charms_core.protocol` | Every WebSocket message on the launcher and realtime-client wires |
+
+## Install
+
+```bash
+pip install charms-core
+```
+
+Python ≥ 3.12. Fully typed (`py.typed`).
+
+## Building a Seed
+
+```python
+from pydantic import BaseModel
+from charms_core.seed import Seed, SeedContext, SeedManifest
+from charms_core.types import Modality, PortSchema
+
+class EchoInput(BaseModel):
+    text: str
+
+class EchoOutput(BaseModel):
+    text: str
+
+class EchoSeed(Seed[EchoInput, EchoOutput, None]):
+    manifest = SeedManifest(id="echo", name="Echo")
+    inputs = [PortSchema(name="text", modality=Modality.TEXT)]
+    outputs = [PortSchema(name="text", modality=Modality.TEXT)]
+    input_model = EchoInput
+    output_model = EchoOutput
+
+    async def load(self, ctx: SeedContext) -> None: ...
+
+    async def run(self, input: EchoInput, config: None = None) -> EchoOutput:
+        return EchoOutput(text=input.text)
+```
+
+Package it (with a `manifest.json`, `pyproject.toml`, and `README.md`) and
+import it into a Charms server's seed registry; contributors then pull and
+run it as a Rune via the launcher.

charms_core-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "charms-core"
+version = "0.1.0"
+description = "Charms shared contracts: node & seed SDK, recipes, chunks, wire protocol, seed packages"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "ArioAtlas" }]
+keywords = ["charms", "ai", "workflow", "distributed-computing", "sdk"]
+# NOTE: no license declared yet — decide one before the next release.
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[project.urls]
+# The public home of these contracts (vendored into the launcher repo).
+Repository = "https://github.com/ArioAtlas/charms-launcher"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/charms_core"]

charms_core-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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}"
+        )