Compiler and plans

uptimely.compiler turns spec into portable execution plans. Its plan subpackage owns the plan models and JSON serialization.

compiler

uptimely.compiler.compiler provides the compilation entry point.

Compile spec into portable execution plans.

Compiler

Turn a Spec instance or JSON path into a portable execution plan.

spec_path instance-attribute

spec_path: Path | None = None

spec instance-attribute

spec: Spec | None = None

features instance-attribute

features = self._validate_features(features)

compile

compile() -> plan.ExecutionPlan

Build and serialize the dependency graph into a portable plan.

callable_node

uptimely.compiler.callable_node represents a callable in the compilation graph.

CallableNode dataclass

One fragment, calculation, or sink function invocation.

function_id instance-attribute

function_id: str

entity instance-attribute

entity: str

feature class-attribute instance-attribute

feature: str | None = None

operation class-attribute instance-attribute

operation: str = 'vectorize'

dataset_id class-attribute instance-attribute

dataset_id: str | None = None

mapping_id class-attribute instance-attribute

mapping_id: str | None = None

output_features class-attribute instance-attribute

output_features: tuple[str, ...] = ()

args class-attribute instance-attribute

args: dict[str, object] = dataclasses.field(default_factory=dict, compare=False, hash=False)

input_features class-attribute instance-attribute

input_features: tuple[str, ...] = ()

row_context class-attribute instance-attribute

row_context: RowContext | None = dataclasses.field(default=None, compare=False, hash=False)

node_id property

node_id: str

Stable graph identifier for this callable invocation.

to_render_data

to_render_data(node_type: str = 'callable') -> dict[str, object]

Return display metadata for rendering this callable node.

execution_graph

uptimely.compiler.execution_graph organizes callable dependencies.

Describe callable invocation dependencies and resolve call ordering.

CallableGraph

Dependency graph built from callable invocations and their feature dependencies.

spec instance-attribute

spec = spec

graph instance-attribute

graph = self._create_graph()

callables property

callables: list[CallableNode]

All callable nodes in the graph.

collapse_input_dataset_id

collapse_input_dataset_id(node: CallableNode) -> str

Infer the input dataset from a collapse node's spec binding.

dataset_for

dataset_for(node: CallableNode) -> spec.Dataset

Return a node's dataset from the validated entity-scoped index.

mapping_for

mapping_for(node: CallableNode) -> spec.Mapping

Return the declaration that produced a callable node.

topology

topology() -> list[list[callable_node_module.CallableNode]]

Return callables grouped by dependency level (topological order).

print_graph

print_graph() -> str

Return a text representation of the callable dependency graph.

print

print() -> None

Print the callable dependency graph.

subset

subset(features: list[str]) -> CallableGraph

Return the dependency closure needed to produce selected features.

dependencies

dependencies(node: CallableNode) -> list[callable_node_module.CallableNode]

Return callables that directly produce the node's dependencies.

get_callable_order

get_callable_order() -> list[callable_node_module.CallableNode]

Return callables in execution order (topological sort).

plan.models

uptimely.compiler.plan.models defines the portable plan and its callables.

Portable execution-plan data transfer objects.

PLAN_VERSION module-attribute

PLAN_VERSION = '0.2.0'

Callable dataclass

One executable function invocation in a portable plan.

id instance-attribute

id: str

operation instance-attribute

operation: str

entrypoint instance-attribute

entrypoint: str

entity_id instance-attribute

entity_id: str

dataset_id instance-attribute

dataset_id: str | None

output instance-attribute

output: str | None

arguments class-attribute instance-attribute

arguments: dict[str, Any] = dataclasses.field(default_factory=dict)

dependency_ids class-attribute instance-attribute

dependency_ids: list[str] = dataclasses.field(default_factory=list)

output_features class-attribute instance-attribute

output_features: list[str] = dataclasses.field(default_factory=list)

input_features class-attribute instance-attribute

input_features: list[str] = dataclasses.field(default_factory=list)

row_context class-attribute instance-attribute

row_context: RowContext | None = None

function_id property

function_id: str

Return the function identifier encoded in this callable's id.

Plan dataclass

Portable, JSON-serializable execution plan.

plan_version instance-attribute

plan_version: str

required_backend instance-attribute

required_backend: str

resources instance-attribute

resources: dict[str, Any]

callables instance-attribute

callables: list[Callable]

stages instance-attribute

stages: list[list[str]]

to_dict

to_dict() -> dict[str, typing.Any]

Return the plan as JSON-compatible data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> Plan

Load a portable plan from a decoded JSON object.

ExecutionPlan dataclass

Portable execution plan with JSON round-trip support.

plan instance-attribute

plan: Plan

callables property

callables: list[Callable]

Return callables in their serialized order.

execution_stages property

execution_stages: list[list[Callable]]

Return staged callables resolved from stage identifiers.

to_dict

to_dict() -> dict[str, typing.Any]

Return the portable plan as plain JSON-compatible data.

export_json

export_json(path: str | Path) -> pathlib.Path

Write the portable plan to JSON.

from_json classmethod

from_json(path: str | Path) -> ExecutionPlan

Load a portable plan without loading or recompiling Spec.

plan.serialization

uptimely.compiler.plan.serialization reads and writes plan JSON.

Serialization helpers for portable execution plans.

export_json

export_json(plan: Plan | ExecutionPlan, path: str | Path) -> pathlib.Path

Serialize a plan to JSON.

from_json

from_json(path: str | Path) -> models.ExecutionPlan

Deserialize an execution plan from JSON.