mplang-nightly 0.1.dev278__py3-none-any.whl → 0.1.dev280__py3-none-any.whl

mplang/__init__.py

@@ -34,6 +34,7 @@ except Exception:
     # Fallback for development/editable installs when package is not installed
     __version__ = "0.0.0-dev"
 
+import mplang.tool as tool
 from mplang import dialects
 from mplang.backends.simp_driver.ops import DRIVER_HANDLERS
 from mplang.backends.simp_worker import SimpWorker
@@ -41,6 +42,8 @@ from mplang.backends.simp_worker.mem import LocalMesh
 from mplang.backends.simp_worker.ops import WORKER_HANDLERS
 from mplang.dialects.simp import make_driver, make_simulator
 from mplang.edsl import (
+    CompiledProgram,
+    FlatIOSignature,
     Graph,
     GraphPrinter,
     Object,
@@ -91,10 +94,10 @@ from mplang.libs.device import (
     set_dev_attr,
 )
 from mplang.libs.device import fetch as device_fetch
+from mplang.runtime.interpreter import Interpreter
 
 # Logging configuration
-from mplang.logging_config import disable_logging, get_logger, setup_logging
-from mplang.runtime.interpreter import Interpreter
+from mplang.utils.logging import disable_logging, get_logger, setup_logging
 
 # =============================================================================
 # Context Management API (JAX-like pattern)
@@ -125,7 +128,7 @@ def _get_context(context: Interpreter | None) -> Interpreter:
 
 
 def evaluate(
-    fn: Callable[..., Any] | TracedFunction,
+    fn: Callable[..., Any] | TracedFunction | CompiledProgram,
     *args: Any,
     context: Interpreter | None = None,
     **kwargs: Any,
@@ -158,15 +161,33 @@ def evaluate(
             return val.runtime_obj
         return val
 
+    def eval_graph(graph: Graph, inputs: list[Any]) -> list[InterpObject]:
+        runtime_inputs = [unwrap_if_interp(v) for v in inputs]
+        raw_result = interp.evaluate_graph(graph, runtime_inputs)
+        return [
+            InterpObject(v, graph.outputs[i].type, interp)
+            for i, v in enumerate(raw_result)
+        ]
+
     with interp:
+        if isinstance(fn, CompiledProgram):
+            if kwargs:
+                raise TypeError(
+                    "mp.evaluate(CompiledProgram, ...) does not accept keyword arguments; "
+                    "pass flat positional inputs only."
+                )
+            if len(args) != fn.signature.input_arity:
+                raise ValueError(
+                    "CompiledProgram requires flat positional inputs matching its signature; "
+                    f"expected {fn.signature.input_arity}, got {len(args)}."
+                )
+
+            return eval_graph(fn.graph, list(args))
+
         if isinstance(fn, TracedFunction):
             inputs = fn.prepare_inputs(*args, **kwargs)
             inputs = [unwrap_if_interp(v) for v in inputs]
-            raw_result = interp.evaluate_graph(fn.graph, inputs)
-            wrapped = [
-                InterpObject(v, fn.graph.outputs[i].type, interp)
-                for i, v in enumerate(raw_result)
-            ]
+            wrapped = eval_graph(fn.graph, inputs)
             return fn.reconstruct_outputs(wrapped)
 
         return fn(*args, **kwargs)
@@ -417,6 +438,9 @@ __all__ = [  # noqa: RUF022
     "WORKER_HANDLERS",
     "make_driver",
     "make_simulator",
+    "tool",
+    "CompiledProgram",
+    "FlatIOSignature",
     # Dialects
     "dialects",
     "register_default_context_factory",

mplang/backends/channel.py

@@ -25,7 +25,7 @@ from typing import Protocol
 
 import spu.libspu as libspu
 
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/backends/simp_driver/http.py

@@ -25,9 +25,9 @@ import httpx
 
 from mplang.backends.simp_driver.state import SimpDriver
 from mplang.edsl import serde
-from mplang.logging_config import get_logger
 from mplang.runtime.interpreter import Interpreter
 from mplang.runtime.object_store import ObjectStore
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/backends/simp_worker/http.py

@@ -54,9 +54,9 @@ from mplang.backends.simp_worker import SimpWorker
 from mplang.backends.simp_worker import ops as _simp_worker_ops  # noqa: F401
 from mplang.edsl import serde
 from mplang.edsl.graph import Graph
-from mplang.logging_config import get_logger
 from mplang.runtime.interpreter import ExecutionTracer, Interpreter
 from mplang.runtime.object_store import ObjectStore
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 
@@ -212,6 +212,7 @@ def create_worker_app(
     world_size: int,
     endpoints: list[str],
     spu_endpoints: dict[int, str] | None = None,
+    enable_tracing: bool = False,
 ) -> FastAPI:
     """Create a FastAPI app for the worker.
 
@@ -224,6 +225,7 @@ def create_worker_app(
         world_size: Total number of workers.
         endpoints: HTTP endpoints for all workers (for shuffle communication).
         spu_endpoints: Optional dict mapping global_rank -> BRPC endpoint for SPU.
+        enable_tracing: Whether to enable execution tracing for profiler.
 
     Returns:
         FastAPI application instance
@@ -236,11 +238,12 @@ def create_worker_app(
     data_root = pathlib.Path(os.environ.get("MPLANG_DATA_ROOT", ".mpl"))
     cluster_id = os.environ.get("MPLANG_CLUSTER_ID", f"__http_{world_size}")
     root_dir = data_root / cluster_id / f"node{rank}"
-    trace_dir = root_dir / "trace"
 
-    # Enable tracing by default for now (or make it configurable via env)
-    tracer = ExecutionTracer(enabled=True, trace_dir=trace_dir)
-    tracer.start()
+    tracer = None
+    if enable_tracing:
+        trace_dir = root_dir / "trace"
+        tracer = ExecutionTracer(enabled=True, trace_dir=trace_dir)
+        tracer.start()
 
     comm = HttpCommunicator(rank, world_size, endpoints, tracer=tracer)
     store = ObjectStore(fs_root=str(root_dir))

mplang/backends/spu_impl.py

@@ -31,9 +31,9 @@ from mplang.backends.tensor_impl import TensorValue
 from mplang.dialects import spu
 from mplang.edsl import serde
 from mplang.edsl.graph import Operation
-from mplang.logging_config import get_logger
 from mplang.runtime.interpreter import Interpreter
 from mplang.runtime.value import WrapValue
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/backends/table_impl.py

@@ -33,9 +33,9 @@ from mplang.backends.tensor_impl import TensorValue
 from mplang.dialects import table
 from mplang.edsl import serde
 from mplang.edsl.graph import Operation
-from mplang.logging_config import get_logger
 from mplang.runtime.interpreter import Interpreter
 from mplang.runtime.value import WrapValue
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/backends/tensor_impl.py

@@ -36,9 +36,9 @@ import mplang.edsl.typing as elt
 from mplang.dialects import dtypes, tensor
 from mplang.edsl import serde
 from mplang.edsl.graph import Operation
-from mplang.logging_config import get_logger
 from mplang.runtime.interpreter import Interpreter
 from mplang.runtime.value import Value, WrapValue
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/cli.py

@@ -49,7 +49,7 @@ from typing import Any, cast
 import uvicorn
 import yaml
 
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/edsl/__init__.py

@@ -53,6 +53,7 @@ from .jit import jit
 from .object import Object
 from .primitive import Primitive, primitive
 from .printer import GraphPrinter, format_graph
+from .program import CompiledProgram, FlatIOSignature
 from .tracer import TracedFunction, TraceObject, Tracer, trace
 from .typing import MPType, ScalarType, SSType, TableType, TensorType, VectorType
 
@@ -65,7 +66,9 @@ TensorObject = Object[TensorType]
 VectorObject = Object[VectorType]
 
 __all__ = [
+    "CompiledProgram",
     "Context",
+    "FlatIOSignature",
     "Graph",
     "GraphPrinter",
     "MPObject",

mplang/edsl/jit.py

@@ -25,7 +25,7 @@ from mplang.edsl.context import (
     get_default_context,
 )
 from mplang.edsl.tracer import Tracer
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 logger = get_logger(__name__)
 

mplang/edsl/primitive.py

@@ -29,7 +29,7 @@ from jax.tree_util import tree_map
 
 from mplang.edsl.context import get_current_context, get_default_context
 from mplang.edsl.object import Object
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from mplang.edsl.typing import BaseType

mplang/edsl/program.py

@@ -0,0 +1,134 @@
+# Copyright 2026 Ant Group Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from mplang.edsl import serde
+from mplang.edsl.graph import Graph
+
+
+@dataclass(frozen=True)
+class FlatIOSignature:
+    """Portable I/O signature for source-free execution.
+
+    Only supports flat positional inputs/outputs corresponding to
+    `graph.inputs` / `graph.outputs`.
+    """
+
+    kind: ClassVar[str] = "flat_list_v0"
+    input_arity: int
+    output_arity: int
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "input_arity": self.input_arity,
+            "output_arity": self.output_arity,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> FlatIOSignature:
+        if data.get("kind") != cls.kind:
+            raise ValueError(f"Unsupported signature kind: {data.get('kind')}")
+        return cls(
+            input_arity=int(data["input_arity"]),
+            output_arity=int(data["output_arity"]),
+        )
+
+
+@serde.register_class
+@dataclass
+class CompiledProgram:
+    """Executable program decoupled from user source.
+
+    This is a *logical model*; packaging (file/zip/etc.) is handled by tool layer.
+
+    Current constraints:
+    - signature is flat positional list I/O.
+    - no closure captures.
+    - no constant outputs (out_imms) unless future signature captures them.
+    """
+
+    _serde_kind: ClassVar[str] = "mplang.CompiledProgram"
+
+    graph: Graph
+    signature: FlatIOSignature
+    required_opcodes: list[str]
+    graph_digest: str
+    required_world_size: int | None = None
+    created_at: str | None = None
+    mplang_version: str | None = None
+    schema_version: int = 1
+    name: str | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "name": self.name,
+            "graph": serde.to_json(self.graph),
+            "signature": self.signature.to_json(),
+            "required_opcodes": list(self.required_opcodes),
+            "graph_digest": self.graph_digest,
+            "required_world_size": self.required_world_size,
+            "created_at": self.created_at,
+            "mplang_version": self.mplang_version,
+        }
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> CompiledProgram:
+        if "schema_version" not in data:
+            raise KeyError("Missing required field: schema_version")
+        schema_version = int(data["schema_version"])
+        if schema_version != 1:
+            raise ValueError(
+                f"Unsupported CompiledProgram schema_version: {schema_version}"
+            )
+
+        graph = serde.from_json(data["graph"])
+        if not isinstance(graph, Graph):
+            raise TypeError(
+                f"Expected graph to deserialize to Graph, got {type(graph).__name__}"
+            )
+
+        signature = FlatIOSignature.from_json(data["signature"])
+
+        required_world_size = data.get("required_world_size")
+        if required_world_size is not None:
+            required_world_size = int(required_world_size)
+        return cls(
+            graph=graph,
+            signature=signature,
+            required_opcodes=list(data.get("required_opcodes", [])),
+            graph_digest=str(data["graph_digest"]),
+            required_world_size=required_world_size,
+            created_at=data.get("created_at"),
+            mplang_version=data.get("mplang_version"),
+            schema_version=schema_version,
+            name=data.get("name"),
+        )
+
+
+def compute_graph_digest(graph: Graph) -> str:
+    """Compute a deterministic digest for a Graph.
+
+    We intentionally avoid `serde.dumps()` because it doesn't sort keys.
+    """
+
+    canonical = json.dumps(serde.to_json(graph), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

mplang/edsl/tracer.py

@@ -36,7 +36,7 @@ from mplang.edsl.graph import Graph
 from mplang.edsl.graph import Value as GraphValue
 from mplang.edsl.object import Object
 from mplang.edsl.typing import BaseType
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from mplang.edsl.primitive import Primitive

mplang/libs/device/api.py

@@ -32,7 +32,7 @@ from mplang.backends import load_builtins
 from mplang.dialects import crypto, simp, spu, tee
 from mplang.edsl.object import Object
 from mplang.libs.device.cluster import Device
-from mplang.logging_config import get_logger
+from mplang.utils.logging import get_logger
 
 load_builtins()
 

mplang/runtime/interpreter.py

@@ -40,9 +40,9 @@ from mplang.edsl.graph import Graph, Value
 from mplang.edsl.object import Object
 from mplang.edsl.registry import get_impl
 from mplang.edsl.typing import BaseType
-from mplang.logging_config import get_logger
 from mplang.runtime.dialect_state import DialectState
 from mplang.runtime.object_store import ObjectStore
+from mplang.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from mplang.edsl.primitive import Primitive

mplang/tool/__init__.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Ant Group Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tool-layer APIs for MPLang.
+
+This package contains utilities that are intentionally *not* part of the core
+EDSL execution surface. In particular, compile/execute decoupling lives here:
+- build a portable `CompiledProgram`
+- pack/unpack to a container format
+
+These helpers must not depend on user source code being available at execution.
+"""
+
+from __future__ import annotations
+
+from mplang.edsl.program import CompiledProgram, FlatIOSignature
+from mplang.tool.program import (
+    compile_program,
+    inspect_artifact,
+    pack,
+    pack_to_path,
+    unpack,
+    unpack_path,
+)
+
+__all__ = [
+    "CompiledProgram",
+    "FlatIOSignature",
+    "compile_program",
+    "inspect_artifact",
+    "pack",
+    "pack_to_path",
+    "unpack",
+    "unpack_path",
+]

mplang/tool/program.py

@@ -0,0 +1,335 @@
+# Copyright 2026 Ant Group Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import io
+import json
+import tarfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import mplang
+from mplang.edsl import serde
+from mplang.edsl.graph import Graph
+from mplang.edsl.program import (
+    CompiledProgram,
+    FlatIOSignature,
+    compute_graph_digest,
+)
+from mplang.edsl.tracer import TracedFunction, trace
+
+DEFAULT_MAX_ARTIFACT_JSON_BYTES = 512 * 1024 * 1024  # 512 MiB
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _iter_graphs(root: Graph) -> list[Graph]:
+    # Use an explicit stack to avoid Python recursion limits.
+    # Also guard against potential region graph cycles.
+    out: list[Graph] = []
+    stack: list[Graph] = [root]
+    visited: set[int] = set()
+    while stack:
+        graph = stack.pop()
+        graph_id = id(graph)
+        if graph_id in visited:
+            continue
+        visited.add(graph_id)
+        out.append(graph)
+
+        for op in graph.operations:
+            if op.regions:
+                stack.extend(op.regions)
+
+    return out
+
+
+def _collect_opcodes(graph: Graph) -> set[str]:
+    opcodes: set[str] = set()
+    for g in _iter_graphs(graph):
+        for op in g.operations:
+            opcodes.add(op.opcode)
+    return opcodes
+
+
+def _collect_parties(graph: Graph) -> set[int]:
+    parties: set[int] = set()
+    for g in _iter_graphs(graph):
+        for op in g.operations:
+            raw = op.attrs.get("parties")
+            if raw is None:
+                continue
+
+            if not isinstance(raw, (list, tuple, set)):
+                raise TypeError(
+                    "Invalid 'parties' attribute: expected list/tuple/set of ints, "
+                    f"got {type(raw).__name__}"
+                )
+            for p in raw:
+                p_int = int(p)
+                if p_int < 0:
+                    raise ValueError("Invalid 'parties' attribute: negative party id")
+                parties.add(p_int)
+    return parties
+
+
+def _compute_required_world_size(graph: Graph) -> int:
+    parties = _collect_parties(graph)
+    if not parties:
+        return 0
+    return max(parties) + 1
+
+
+def _validate_traced_for_artifact(traced: TracedFunction) -> None:
+    # Restriction: no closure captures
+    if traced.captured:
+        raise ValueError(
+            "CompiledProgram does not support closure captures; "
+            "please refactor to pass all values explicitly."
+        )
+
+    # Restriction: no constant outputs (out_imms)
+    if traced.out_imms:
+        raise ValueError(
+            "CompiledProgram does not support constant outputs (out_imms); "
+            "return only traced values (graph outputs)."
+        )
+
+    # Restriction: signature is flat positional list I/O.
+    # We do not preserve (args, kwargs) pytree metadata.
+    # We therefore require all runtime-provided inputs correspond exactly to graph.inputs.
+    if len(traced.graph.inputs) != len(traced.in_var_pos):
+        raise ValueError(
+            "CompiledProgram requires flat positional inputs that map 1:1 to graph.inputs; "
+            f"got graph.inputs={len(traced.graph.inputs)} but in_var_pos={len(traced.in_var_pos)}."
+        )
+
+
+def _validate_program(program: CompiledProgram) -> None:
+    if program.signature.kind != FlatIOSignature.kind:
+        raise ValueError(f"Unsupported signature kind: {program.signature.kind}")
+
+    if program.signature.input_arity != len(program.graph.inputs):
+        raise ValueError(
+            "Signature input_arity does not match graph.inputs: "
+            f"input_arity={program.signature.input_arity}, inputs={len(program.graph.inputs)}"
+        )
+    if program.signature.output_arity != len(program.graph.outputs):
+        raise ValueError(
+            "Signature output_arity does not match graph.outputs: "
+            f"output_arity={program.signature.output_arity}, outputs={len(program.graph.outputs)}"
+        )
+
+    expected_opcodes = sorted(_collect_opcodes(program.graph))
+    if sorted(program.required_opcodes) != expected_opcodes:
+        raise ValueError(
+            "required_opcodes mismatch with graph content; "
+            "artifact may be corrupted or constructed inconsistently."
+        )
+
+    actual_digest = compute_graph_digest(program.graph)
+    if program.graph_digest and program.graph_digest != actual_digest:
+        raise ValueError(
+            "Graph digest mismatch: "
+            f"expected={program.graph_digest}, actual={actual_digest}"
+        )
+
+    expected_world_size = _compute_required_world_size(program.graph)
+    if (
+        program.required_world_size is not None
+        and program.required_world_size != expected_world_size
+    ):
+        raise ValueError(
+            "required_world_size mismatch with graph content; "
+            f"expected={expected_world_size}, got={program.required_world_size}."
+        )
+
+    # Ensure JSON serialization works (fail fast for non-serde attrs).
+    serde.to_json(program)
+
+
+def compile_program(
+    fn_or_traced: Any,
+    *args: Any,
+    context: Any | None = None,
+    name: str | None = None,
+    **kwargs: Any,
+) -> CompiledProgram:
+    """Compile (trace) into a source-free executable `CompiledProgram`.
+
+    Restrictions (enforced):
+    - no closure captures
+    - no constant outputs (`out_imms` must be empty)
+    - signature is flat list (positional) I/O
+
+    Note: `in_imms` (compile-time constants) are allowed: they are baked into the graph.
+    """
+
+    traced: TracedFunction
+    if isinstance(fn_or_traced, TracedFunction):
+        traced = fn_or_traced
+    else:
+        if context is not None:
+            with context:
+                traced = trace(fn_or_traced, *args, **kwargs)
+        else:
+            traced = trace(fn_or_traced, *args, **kwargs)
+
+    _validate_traced_for_artifact(traced)
+
+    signature = FlatIOSignature(
+        input_arity=len(traced.graph.inputs),
+        output_arity=len(traced.graph.outputs),
+    )
+
+    required_opcodes = sorted(_collect_opcodes(traced.graph))
+    graph_digest = compute_graph_digest(traced.graph)
+    required_world_size = _compute_required_world_size(traced.graph)
+
+    program = CompiledProgram(
+        graph=traced.graph,
+        signature=signature,
+        required_opcodes=required_opcodes,
+        graph_digest=graph_digest,
+        required_world_size=required_world_size,
+        created_at=_utc_now_iso(),
+        mplang_version=getattr(mplang, "__version__", None),
+        name=name or traced.name,
+    )
+    return program
+
+
+def pack(program: CompiledProgram, *, compress: bool = True) -> bytes:
+    """Pack a `CompiledProgram` into portable bytes.
+
+    Container format (recommended): a `tar.gz` archive containing a single
+    human-readable JSON file `artifact.json`.
+
+    This allows users to inspect artifacts via:
+        `tar -xzf program.tar.gz && cat artifact.json`
+
+    If `compress=False`, returns an uncompressed tar archive (still extractable
+    via `tar -xf`).
+    """
+
+    artifact_json = json.dumps(
+        serde.to_json(program),
+        ensure_ascii=False,
+        indent=2,
+        sort_keys=True,
+    ).encode("utf-8")
+
+    buf = io.BytesIO()
+    mode: Literal["w:gz", "w"] = "w:gz" if compress else "w"
+    with tarfile.open(fileobj=buf, mode=mode) as tf:
+        info = tarfile.TarInfo(name="artifact.json")
+        info.size = len(artifact_json)
+        tf.addfile(info, io.BytesIO(artifact_json))
+
+    return buf.getvalue()
+
+
+def pack_to_path(
+    program: CompiledProgram, path: str | Path, *, compress: bool = True
+) -> Path:
+    """Pack and write artifact to disk.
+
+    Args:
+        program: Program to pack.
+        path: Output path (typically ends with `.tar.gz`).
+        compress: Whether to gzip the tar archive.
+
+    Returns:
+        The resolved output path.
+    """
+
+    out_path = Path(path).expanduser().resolve()
+    out_path.write_bytes(pack(program, compress=compress))
+    return out_path
+
+
+def unpack(
+    data: bytes, *, max_artifact_json_bytes: int = DEFAULT_MAX_ARTIFACT_JSON_BYTES
+) -> CompiledProgram:
+    """Unpack bytes into a `CompiledProgram`.
+
+    Supported container format: tar(.gz) containing `artifact.json`.
+    """
+
+    try:
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:*") as tf:
+            member = tf.getmember("artifact.json")
+
+            if not member.isfile():
+                raise ValueError("artifact.json is not a regular file")
+
+            if member.size < 0:
+                raise ValueError("Invalid artifact.json size in tar header")
+
+            if member.size > max_artifact_json_bytes:
+                raise ValueError(
+                    "artifact.json is too large to unpack safely: "
+                    f"size={member.size} bytes, limit={max_artifact_json_bytes} bytes"
+                )
+
+            f = tf.extractfile(member)
+            if f is None:
+                raise ValueError("artifact.json not found in tar archive")
+            payload = json.loads(f.read().decode("utf-8"))
+    except (tarfile.ReadError, KeyError, OSError, json.JSONDecodeError) as exc:
+        raise ValueError(
+            "Invalid artifact container: expected tar(.gz) with artifact.json"
+        ) from exc
+
+    program = serde.from_json(payload)
+    if not isinstance(program, CompiledProgram):
+        raise TypeError(
+            f"Expected artifact.json to deserialize to CompiledProgram, got {type(program).__name__}"
+        )
+
+    _validate_program(program)
+    return program
+
+
+def unpack_path(path: str | Path) -> CompiledProgram:
+    """Read an artifact from disk and unpack it."""
+
+    in_path = Path(path).expanduser().resolve()
+    return unpack(in_path.read_bytes())
+
+
+def inspect_artifact(data: bytes) -> dict[str, Any]:
+    """Return a JSON-friendly inspection report without executing."""
+
+    program = unpack(data)
+    return {
+        "schema_version": program.schema_version,
+        "name": program.name,
+        "mplang_version": program.mplang_version,
+        "created_at": program.created_at,
+        "graph_digest": program.graph_digest,
+        "required_world_size": program.required_world_size,
+        "signature": program.signature.to_json(),
+        "required_opcodes": program.required_opcodes,
+        "graph": {
+            "inputs": len(program.graph.inputs),
+            "ops": len(program.graph.operations),
+            "outputs": len(program.graph.outputs),
+            "region_count": sum(len(op.regions) for op in program.graph.operations),
+        },
+    }

mplang/utils/__init__.py

@@ -22,13 +22,17 @@ from .func_utils import (
     var_demorph,
     var_morph,
 )
+from .logging import disable_logging, get_logger, setup_logging
 
 __all__ = [
     "MorphStruct",
+    "disable_logging",
+    "get_logger",
     "is_treedef_list",
     "list_reconstruct",
     "list_split",
     "normalize_fn",
+    "setup_logging",
     "validate_morph_struct",
     "var_demorph",
     "var_morph",

mplang/{logging_config.py → utils/logging.py}

@@ -12,8 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-Logging configuration for MPLang.
+"""Logging configuration for MPLang.
 
 This module provides a unified logging setup for the MPLang library.
 When MPLang is used as a library, logging is disabled by default (NullHandler),
@@ -31,6 +30,8 @@ Example usage:
     ... )
 """
 
+from __future__ import annotations
+
 import logging
 import sys
 from typing import Any, Literal
@@ -52,8 +53,7 @@ def setup_logging(
     force: bool = False,
     propagate: bool = False,
 ) -> None:
-    """
-    Configure logging for MPLang.
+    """Configure logging for MPLang.
 
     This function sets up a logger for all MPLang components. By default,
     MPLang uses a NullHandler to suppress log output when used as a library.
@@ -143,8 +143,7 @@ def setup_logging(
 
 
 def disable_logging() -> None:
-    """
-    Disable all MPLang logging by adding a NullHandler.
+    """Disable all MPLang logging by adding a NullHandler.
 
     This is useful for testing or when you want to completely suppress
     MPLang log output.
@@ -163,21 +162,9 @@ def disable_logging() -> None:
 
 
 def get_logger(name: str) -> logging.Logger:
-    """
-    Get a logger for a specific MPLang module.
+    """Get a logger for a specific MPLang module.
 
-    This function should be used by all MPLang modules to create their loggers.
     The logger name will be prefixed with 'mplang' automatically if not already.
-
-    Args:
-        name: Module name, typically __name__ from the calling module.
-
-    Returns:
-        A logger instance for the specified module.
-
-    Example:
-        >>> # In mplang/edsl/tracer.py
-        >>> logger = get_logger(__name__)  # Creates 'mplang.edsl.tracer' logger
     """
     # Ensure the logger name is under mplang hierarchy
     if not name.startswith(MPLANG_LOGGER_NAME):

{mplang_nightly-0.1.dev278.dist-info → mplang_nightly-0.1.dev280.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mplang-nightly
-Version: 0.1.dev278
+Version: 0.1.dev280
 Summary: Multi-Party Programming Language
 Author-email: SecretFlow Team <secretflow-contact@service.alipay.com>
 License:                                  Apache License

{mplang_nightly-0.1.dev278.dist-info → mplang_nightly-0.1.dev280.dist-info}/RECORD

@@ -1,30 +1,29 @@
-mplang/__init__.py,sha256=QzbdmzTomqQwTZmLKayovb2cl2qcFVzvM_qxlfFfRQ0,13607
-mplang/cli.py,sha256=NW0GmxZeRC4rrYg8RVBlZiDjkihBXGcHmrll-JFOqWM,20317
+mplang/__init__.py,sha256=RQ0z5slM6eNgWlTqGkn67tYDvq8ZzZBfMD2XCdQR86c,14518
+mplang/cli.py,sha256=JQRdLlbycK7awumcY60F4Nw7ozRebfe5cpNEDyRQ3jw,20316
 mplang/cli_guide.md,sha256=hKC6AKgJn-lM_wZ0CzZIP2QUBxGPnT0Op_1YyeUhCfI,3581
-mplang/logging_config.py,sha256=6Zm1Z_EBnzxAfeKr94xiLpWYDD8fa4ZEs2g_kMoH8eI,7579
 mplang/py.typed,sha256=RyhZV7Yxo8BvEoBiFz5fH3IWVqQKTcBBE-bzjx_N5GQ,583
 mplang/backends/__init__.py,sha256=EnKHmOX4YgvNVA42k_KfiS-Vn860yN7Rj9XkUU0g9ys,2042
 mplang/backends/bfv_impl.py,sha256=qobGXe7ldWvYVcqdkNsTcVdNV-hUVE9-Ks5pd3X0Mvc,25691
-mplang/backends/channel.py,sha256=eCjFkiuRvOtFdOC63mTBhkb958EQ7aikc16BeSKL_QY,6877
+mplang/backends/channel.py,sha256=MZwaF0DkkBF_98xdQ8ri0kROJmnCS1ldbwdZUi-sWAU,6876
 mplang/backends/crypto_impl.py,sha256=m5tbZpedn4McG5t6HIaEjhTQUFOIaEDMdyEG0499S0Y,23187
 mplang/backends/field_impl.py,sha256=lIghppy0i8QL7aTNCr8tNWjC_bvOXBIKLnavaO0fIOA,14773
 mplang/backends/func_impl.py,sha256=vhkSJnvgSzvQWXqOE40O8npqOmtNqLxefzv9ETuQODQ,3573
 mplang/backends/phe_impl.py,sha256=CefRpFrRJvbZm3X58OYOFAyNZXKDp081Q6CT8fhdreE,4118
 mplang/backends/simp_design.md,sha256=u4YeDLKk5avsueXhzPtt4OUBToBmurOVK_BWTKTJ7w0,5246
-mplang/backends/spu_impl.py,sha256=WmhyMx2vAfksRLPYY0gwBLUOgebrRZV5cF9YgfDKF2s,9527
+mplang/backends/spu_impl.py,sha256=mkyNCwHC4N7zZ23mCRdOqJWbKv8dxH-Tqi14cTyhGSA,9526
 mplang/backends/spu_state.py,sha256=tgwOiWN6zfP-fBx2rN2cNnC-Y9GrSArqU-ZBT3NdXls,6557
 mplang/backends/store_impl.py,sha256=BdrCfNhFbcjswIvfxD2XKGYeBfBrmEQA3pj2-EDzFcI,2213
-mplang/backends/table_impl.py,sha256=rEypHu4-crx2sVZAnGjq7cQ6rJIQpAEdLv66c1IWtcc,27618
+mplang/backends/table_impl.py,sha256=SFbZJpZS1SdRxxlYfQjc69qcy-2hVfVAYEapNRaTTiI,27617
 mplang/backends/tee_impl.py,sha256=5yed94Lr55hgSDT6j3FjdTboqzhl4HpJ9lGk1YGZBXQ,7026
-mplang/backends/tensor_impl.py,sha256=cYpkHfD6HpoQir06_CGYIcysXvrA85zjeCyqOvlA4Hk,18964
+mplang/backends/tensor_impl.py,sha256=iIOsvSXiRsQWbC8BBfPUpOUhAXJW8VY11l0BxsMVYPo,18963
 mplang/backends/simp_driver/__init__.py,sha256=pQkHGR8HagnPB4OqagPZY-Ul19y6HjIJ5dY6QXZrBH8,1243
-mplang/backends/simp_driver/http.py,sha256=BuJpcXzIVM3pDCbKMU7zRE89RLmQe_3e_4C4GH38IEA,5602
+mplang/backends/simp_driver/http.py,sha256=isZvDHrrCgi07u5_sFfTYvR4p2CI3vs8zwnk9u6O3Ko,5601
 mplang/backends/simp_driver/mem.py,sha256=EAsDO4Zl2pHf8TY4K_whluhbAwaT1NhktBM9u4g5yYE,9101
 mplang/backends/simp_driver/ops.py,sha256=WYObWDRCsiXH0UBWZX5vD5W98ZPkd88U_qBV8SE5rA8,4503
 mplang/backends/simp_driver/state.py,sha256=dNmYMFN2D2BBdgs6C0YLaHrfaBRMgs05UNxMWw6tZIs,1713
 mplang/backends/simp_driver/values.py,sha256=Lz1utNSIzH-dCzZAEjU6JRcxPsfKGfUJrYl6gIuMOGw,1509
 mplang/backends/simp_worker/__init__.py,sha256=gdrSY1-MDkupCoJ8xwwH7em7fgVWv3J4gBJ45uHdzgg,961
-mplang/backends/simp_worker/http.py,sha256=90nJnNLSM9TUVRxhAFq9pyNk0LwmSmvgnv3Tb8KFWSE,12660
+mplang/backends/simp_worker/http.py,sha256=y5qpDpfM6vKBsicr2wCkgn-RHnED-b5J0r9hBJxrgN8,12746
 mplang/backends/simp_worker/mem.py,sha256=tMGiRppeca0TnY8WdqYQMQvsx5UVswCqdeOhiDlLQBs,3574
 mplang/backends/simp_worker/ops.py,sha256=ntxfkD4e6Il4w7FshK1ODcUCUPMlipt33pDY_x5iC0U,5661
 mplang/backends/simp_worker/state.py,sha256=nIu0ybvdYqRqp0TkoSneUF2u31evDHucCRduVBaDals,1445
@@ -42,16 +41,17 @@ mplang/dialects/table.py,sha256=i9ruyh91_tSWu9rsLomrBUfqRdbHiZMMMJzNKfMrAUc,1353
 mplang/dialects/tee.py,sha256=BMFSbeK-Ck2jQP4qY9bZeNYTxEa7uEtUWLZLC4BPQxk,10111
 mplang/dialects/tensor.py,sha256=7aAYKaMaFjJ8N25yPFnmVhUuUdKJYy-M-a4NsZGE7kY,39893
 mplang/edsl/README.md,sha256=viflvdRojOa6Xk_UMRPqpuPGXcPGmdlv2-XR6LO7B58,7592
-mplang/edsl/__init__.py,sha256=ARYS7FkkSXwjWCsPLtWc9kL5OaR4wd5zCQhFTkzZUp0,2598
+mplang/edsl/__init__.py,sha256=WL4efo6uY1br781_8IaCkSi7yCUldcfJfbtFsn6Fdj4,2698
 mplang/edsl/context.py,sha256=Ln8n3bDe8_ISe42TAGzUuz8fw57-tu1APuihMfAtW1Y,10075
 mplang/edsl/graph.py,sha256=nCeCN7-bxfzyv40fmxcEXOaVUx14cOCaHfFb7A9OBnE,14968
-mplang/edsl/jit.py,sha256=7eLZHoIuL5FZo9G5eF9nI4EeayLK-OvJ0NoH3VG5vLI,2393
+mplang/edsl/jit.py,sha256=urXV68sQ-CjYuWGQSLj9ZAxP3YieISt2tfr2GEo-vCQ,2392
 mplang/edsl/object.py,sha256=dBl58q-ondjpjPNBh8zZvIEj6pJw2yEoz6TCaM_oleA,1906
-mplang/edsl/primitive.py,sha256=gDrn4FH682DUOgTqcQ2-9aqDYJau9L8E1ElswyOmmdw,10859
+mplang/edsl/primitive.py,sha256=N9HEsXJuQTx_haLafUluL4EuIS2AKHNekZvCRWu5o-0,10858
 mplang/edsl/printer.py,sha256=drmfRkdCNqbkRfSDmejxtO-rEAaM13QyHB3AbAmKVFk,4393
+mplang/edsl/program.py,sha256=_JdEU2-nb79VlFLcgMJf4JS30TARBeUIzno0y0SFVsg,4467
 mplang/edsl/registry.py,sha256=hudXZPUrUUueEwgksDKN0cnE3iiXucuTaDdDK8uSPmk,6822
 mplang/edsl/serde.py,sha256=8K94laE8ObeGuBoF6m7g3A-xEe98EvqQ_6ZPPspddAY,11641
-mplang/edsl/tracer.py,sha256=EWN3eMVRG-CZsamTyINOnhhEUKhgd4CYwFMWeRpjycU,23129
+mplang/edsl/tracer.py,sha256=WQFNL2ZgXSLjxD4JA7cXIDUKIQXe3aZ94qer57IKPXc,23128
 mplang/edsl/typing.py,sha256=Vp0r_oTyFrOhwwpVD_6XAX0sSsKvR04X-KdihkmD4QA,29287
 mplang/kernels/Makefile,sha256=5PoPpajcb_8ByPGNHzVytmovXUwkjJs_K8MbXX9qDYs,1033
 mplang/kernels/__init__.py,sha256=J_rDl9lAXd7QL3Nt_P3YX6j9yge7ssguSaHuafPZNKE,876
@@ -62,7 +62,7 @@ mplang/kernels/okvs_opt.cpp,sha256=qKkwHGGv7ayvIRW46PrQZZ7ej4b58Drbr3BlqEK506U,1
 mplang/kernels/py_kernels.py,sha256=EXK2ByfRsVpBqp1etDyCb_qExT0obiytcNFXYpRyxpo,12070
 mplang/libs/collective.py,sha256=1RhwnpKwjLvbZ5UgmCMkO6brwqHEIdkW_zymRawwTW4,10668
 mplang/libs/device/__init__.py,sha256=UHPGQ9JVedXy6AQo-ixQooS2R8eTwJEu7-p8A5_po78,1248
-mplang/libs/device/api.py,sha256=DjlAlKYgC9j8V1eBwa9o7cy-Y4cASCmMiccQiA6a9tc,28870
+mplang/libs/device/api.py,sha256=vkwoHjIlwEivSUn1_NLf47pOq34gO6yCXTWRDYdgN2I,28869
 mplang/libs/device/cluster.py,sha256=YUqYZ_IBS6rpV5ejUFP3kTxcTQHSyeDeuaJcsiFY_Js,12508
 mplang/libs/ml/__init__.py,sha256=kUR6V74kWmGnOUdmLuGAP1xebW7y-NBOmHyHK-kdqWg,784
 mplang/libs/ml/sgb.py,sha256=g5x1PQnV7oRzheyu6PiDooqmBWI9jMvLHkIHrNnMoDk,60211
@@ -91,13 +91,16 @@ mplang/libs/mpc/vole/ldpc.py,sha256=gOmIbyOjkGE5lewyatl3p6FizNNH8LZ_1oOhp_-TOck,
 mplang/libs/mpc/vole/silver.py,sha256=EIxhpFIVNBemgeIZzCu5Cz_4wysxRm9b1Xfu0xiweVQ,12218
 mplang/runtime/__init__.py,sha256=VdUwJ3kDaI46FvGw7iMGwcsjt0HTGmmRmaBwj99xKIw,620
 mplang/runtime/dialect_state.py,sha256=HxO1i4kSOujS2tQzAF9-WmI3nChSaGgupf2_07dHetY,1277
-mplang/runtime/interpreter.py,sha256=wcCWXpAGylqdw_HecR4suJtwmozHLrK5x6Q8xM-Pn24,43593
+mplang/runtime/interpreter.py,sha256=yWcUDbAfjKgkx09rYTHrIcrs4KzbV3y8tkC7VrqQRJ4,43592
 mplang/runtime/object_store.py,sha256=yT6jtKG2GUEJVmpq3gnQ8mCMvUFYzgBciC5A-J5KRdk,5998
 mplang/runtime/value.py,sha256=EqlhSgxLTJi_FF3ppyKjMe4eHS6-ROx-zK1YesG1U4o,4311
-mplang/utils/__init__.py,sha256=toubeyISiT6WDdITdfAvdY2iXVZU3PKVNWVeC9sYxuA,947
+mplang/tool/__init__.py,sha256=9K-T50W_vClUlyERcVx5xGZaeyv0Ts63SaQX6AZtjIs,1341
+mplang/tool/program.py,sha256=W3H8bpPirnoJ4ZrmyPYuMCPadJis20o__n_1MKqCsWU,11058
+mplang/utils/__init__.py,sha256=Hwrwti2nfPxWUXV8DN6T1QaqXH_Jsd27k8UMSdBGUns,1073
 mplang/utils/func_utils.py,sha256=aZ-X43w8JKJgiF-IUMS0G7QqrNeoTM5ZPzRNd-tKxpw,5180
-mplang_nightly-0.1.dev278.dist-info/METADATA,sha256=_Oqywn7lgVIsrzHL__BPIIq8WUu-W1a2YWiweqrTDOE,16783
-mplang_nightly-0.1.dev278.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mplang_nightly-0.1.dev278.dist-info/entry_points.txt,sha256=mG1oJT-GAjQR834a62_QIWb7litzWPPyVnwFqm-rWuY,55
-mplang_nightly-0.1.dev278.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-mplang_nightly-0.1.dev278.dist-info/RECORD,,
+mplang/utils/logging.py,sha256=9dMhwprVbx1WMGJrgoQbWmV50vyYuLU4NSPnetcl1Go,7237
+mplang_nightly-0.1.dev280.dist-info/METADATA,sha256=IG4D8STIc2G7ZtQAz3OlKptLansk_hvB03-2M2HNZCw,16783
+mplang_nightly-0.1.dev280.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mplang_nightly-0.1.dev280.dist-info/entry_points.txt,sha256=mG1oJT-GAjQR834a62_QIWb7litzWPPyVnwFqm-rWuY,55
+mplang_nightly-0.1.dev280.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mplang_nightly-0.1.dev280.dist-info/RECORD,,