API Documentation#

Module contents#

Python package to make AI models deployment-ready for any hardware.

class embedl_deploy.Trace(value)[source]#

Bases: Enum

Tracing method used to produce the graph.

EXPORT = 'export'#
NONE = 'none'#
SYMBOLIC = 'symbolic'#
class embedl_deploy.TransformationPlan(model: GraphModule, matches: dict[str, dict[str, ~embedl_deploy._internal.core.patterns.main.PatternMatch]]=<factory>)[source]#

Bases: object

Editable transformation plan.

Returned by get_transformation_plan(). The matches dict maps input_node_name → pattern_class_name → PatternMatch. Toggle match.apply = False to skip specific matches before calling apply_transformation_plan().

matches: dict[str, dict[str, PatternMatch]]#

Nested dict of discovered matches, keyed by the last matched node’s name and the pattern class name.

model: GraphModule#

The graph (not yet modified by replacements).

class embedl_deploy.TransformationResult(model: GraphModule, report: TransformationReport, matches: list[PatternMatch])[source]#

Bases: object

Result of applying a transformation plan.

Returned by apply_transformation_plan().

matches: list[PatternMatch]#

The actual PatternMatch objects that were applied.

model: GraphModule#

The transformed model with fused / quantized modules.

report: TransformationReport#

Summary of what was applied and what was skipped.

embedl_deploy.apply_transformation_plan(plan: TransformationPlan) → TransformationResult[source]#

Apply the enabled matches from plan.

Only matches with apply=True are applied via replace(). The plan’s model is modified in place. After replacement, dead code and orphaned submodules are removed, the graph is linted and recompiled, and shape metadata is re-propagated when available. The model’s training state is preserved.

Parameters:

plan – The plan to apply (from get_transformation_plan()).

Returns:

A TransformationResult containing model (transformed), report (summary), and matches (applied matches).

Raises:

ValueError – If any nodes are included in more than one enabled pattern.

Example:

result = apply_transformation_plan(plan)
print(result.report)
torch.onnx.export(result.model, x, "deployed.onnx")
embedl_deploy.get_transformation_plan(graph_module: GraphModule, patterns: Sequence[type[Pattern]]) → TransformationPlan[source]#

Find all non-overlapping tree-based pattern matches.

Each pattern’s match() must return PatternMatch objects with a populated tree_match. Overlapping matches are resolved by marking later overlaps as apply=False.

Returns a TransformationPlan that can be inspected and edited before calling apply_transformation_plan().

Parameters:

  • graph_module – The traced graph module to analyze.

  • patterns – Patterns to search for. Order matters: patterns are matched in sequence, and earlier matches claim nodes first. Supply longest (most specific) patterns first to ensure they take priority over shorter ones when sub-graphs overlap.

Returns:

A TransformationPlan containing graph_module and matches (a nested dict of discovered pattern matches).

Example:

from embedl_deploy import get_transformation_plan, prepare_graph
from embedl_deploy.backend import get_backend

graph_module = prepare_graph(model, args)
plan = get_transformation_plan(
    graph_module, patterns=get_backend().fusion_patterns
)
for node, pats in plan.matches.items():
    for name, match in pats.items():
        print(f"{node}: {name} apply={match.apply}")
embedl_deploy.prepare_graph(model: Module | GraphModule, args: tuple[Any, ...], *, trace: Trace = Trace.EXPORT) → GraphModule[source]#

Trace, deep-copy, and propagate shapes.

Produces a GraphModule ready for pattern matching. The original model is deep-copied and never modified.

Parameters:

  • model – The model to prepare. A GraphModule may be re-traced (e.g. to apply recomposition via Trace.EXPORT) or used as-is with Trace.NONE.

  • args – Example inputs for tracing and shape propagation.

  • trace – Tracing method. Trace.EXPORT (default) uses torch.export.export() followed by recomposition; Trace.SYMBOLIC uses symbolic_trace(); Trace.NONE skips tracing (requires a GraphModule).

Returns:

A deep-copied GraphModule with shape metadata.

embedl_deploy.transform(model: Module | GraphModule, args: tuple[Any, ...], patterns: Sequence[type[Pattern]] | None = None, *, trace: Trace = Trace.EXPORT) → TransformationResult[source]#

Apply pattern transformations to model in one step.

Conversion patterns are applied iteratively until no new matches are found, then fusion patterns are matched and applied in a single pass. Recomposition is handled automatically during tracing (see prepare_graph()). The original model is deep-copied and never modified.

Parameters:

  • model – The model to transform. A GraphModule may be re-traced or used as-is depending on trace.

  • args – Example inputs for tracing.

  • patterns – Patterns to match and apply. When None (the default), the active backend’s conversion_patterns and fusion_patterns are used. Order matters: patterns are matched in sequence, and earlier matches claim nodes first. Supply longest (most specific) patterns first to ensure they take priority over shorter ones when sub-graphs overlap.

  • trace – Tracing method. Trace.EXPORT (default) uses torch.export.export() followed by recomposition; Trace.SYMBOLIC uses symbolic_trace(); Trace.NONE skips tracing (requires a GraphModule).

Returns:

A TransformationResult containing model (transformed), report (summary), and matches (applied matches). The report and matches reflect the fusion pass only – conversion matches become stale after fusion rewrites the graph, so only the final pass is reported. Use get_transformation_plan() and apply_transformation_plan() individually when per-phase reporting is needed.

Example:

from embedl_deploy import transform

result = transform(model, args)
deployable_model = result.model

Subpackages#