Getting started

Start in Report Workbench when you are writing around values and tables. Start in PXFLOW Studio or the Python SDK when the calculation structure comes first. The two paths meet at the Flow's public inputs and results.

Current Component boundary

Current @px.component registers process-local companion metadata and annotation-derived ports. It does not compile a package, resolve an installed release, or create a durable ComponentRef. Production exposes no new third-party Component placement; an already-saved exact target is preserved as read-only unsupported. A current internal/test resolver primitive can persist an exact ref, but caller and release policy do not expose it as a production third-party workflow. The API accepts ProjectScope, and current V1 storage, catalog, detail, and execution reads enforce that exact Workspace/Project data path. They do not bind the requested scope to the authenticated principal. Third-party Component activation remains blocked until Project authorization and execution-trust closure are implemented. Successor V2 Canvas UI is host-owned component.declarative@2 only, settings are declared through component-declared-settings@1, at most eight per declaration, and the host draws each control from its own registry, and rich surfaces belong to component-rich-surface-declaration@1, the RFC-016 successor.

A Report and a Flow are sibling documents in a Project. Author the Report in Workbench or the SDK, compose the Flow in the SDK or Studio, and connect Report values and result positions at the Flow public boundary.

Choose a starting path

Start with a Report

1. Open a Project from My projects and choose Report.
2. Create a Report and write its body, input values, or tables.
3. For a new table input, place the caret in an empty paragraph and choose @ Insert → PXFLOW → Use report input to create the connected table. You can instead select existing text or a number. Direct promotion of an existing ordinary table range is planned.
4. At the intended result position, choose @ Insert → PXFLOW → Show result.
5. Save the Report, then choose Run for that connection.
6. Review the result in the Report and in Project Activity.

Follow the first Report connection in Report Workbench

Start with a Flow on screen

1. Open a Project from My projects and choose PXFLOW.
2. Create a Flow, enter a clear name and description, and review the suggested Flow key.
3. Place prepared Functions as Nodes and connect compatible ports. Stored Component targets remain readable as unsupported while their live authoring surface is planned.
4. Use Validate → Save → Run, then inspect the Run and Result area.
5. To place that Result in a Report, continue with the Report connection guide.

Build your first Flow on the canvas

Start with the Python SDK

The smallest Flow is written like this. It places one calculation as a Node, connects two inputs, exposes one result, and runs the Flow.

from pipelinexlab import px


class CheckResults(px.Results):
    utilization: float


@px.function(
    key="check_resistance",
    version="1.0.0",
    description="Checks girder demand against resistance.",
)
def check_resistance(
    span: float,
    demand: float,
) -> CheckResults:
    resistance = span * 100.0
    return CheckResults(utilization=demand / resistance)


flow = px.Flow(
    "girder_check",
    label="Girder check",
    description="Checks girder demand against resistance.",
)
span = flow.input("span", float, unit="m", description="Clear span.")
demand = flow.input("demand", float, unit="kN.m", description="Design demand.")
check = flow.node("resistance_check", check_resistance)
flow.connect(span, check.inputs.span)
flow.connect(demand, check.inputs.demand)
flow.result("utilization", check.results.utilization)


if __name__ == "__main__":
    client = px.Client(workspace="engineering", project="bridge_project")
    run = client.run(flow, span=12.0, demand=860.0)

Each statement becomes something you can see in PXFLOW.

Code	What appears on screen
px.Flow(...)	One Flow in PXFLOW
flow.input(...)	A public input port on the Canvas
flow.node(...)	A Node box on the Canvas
flow.connect(...)	A connection between Nodes
flow.result(...)	A public result port on the Canvas
client.run(...)	A Run record in the Run·Result area

Replace workspace and project with the values from Project settings. To author the Report in the same file and link it with report.connect_flow(...), continue below.

Author a Flow and Report with Python

Python names follow one visible ownership rule:

from pipelinexlab import px

flow = px.Flow(                       # PipelineXLab root type
    "girder_check",
    label="Girder check",
    description="Checks a girder for the supplied span.",
)
span = flow.input(                    # action owned by this Flow
    "span",
    float,
    description="Clear girder span.",
)
client = px.Client(workspace="engineering", project="bridge")
run = client.run(flow, span=12.0)    # action owned by this client

Use px. for current PipelineXLab root types and decorators, including px.Flow, px.Report, px.Client, px.Results, and @px.function. After an object is created, call methods on the variable that holds it—for example, flow = px.Flow(...) followed by flow.node(...). Keep installed package targets under their package namespace, such as midas_components.model_viewer. Every current public Python surface uses px.Client(workspace="...", project="..."); a host-injected lowercase px.client() convenience remains a planned contract.

Understand what each document owns

Item	What it stores	Where you edit it
Report	Body, authored values and tables, Flow mappings, and result positions	Report Workbench or px.Report
Flow	Public inputs and results, Nodes, and internal port connections	PXFLOW Studio or px.Flow
Run	One execution record for a saved Flow revision and its inputs	Run and Result area
Result	Values, artifacts, and execution evidence saved by a Run	Result area and read-only Report positions

Creating a Report connection selects a Flow's public port and saves the mapping with the Report. The Flow continues to own its calculation structure, so the same Flow can serve several Reports with different authored values and result positions.

Learn the core concepts

Concept	What it means	Where you see it
Project	The workspace containing Reports, Flows, Component packages, Runs, and Results	Project Home
Report	Written content, authored data, and selected Flow results	Report Workbench
Function	A reusable calculation capability	Definitions and Function Reference Node details
Component	Current companion metadata or, after both P0 closures, an admitted exact capability	Already-saved exact metadata is unsupported; successor placement is contract-only
Node	One explicit flow.node("node_key", target) placement in a Flow	One box on the Canvas
Subflow · Group	Editable visual membership between existing Nodes in the same Flow	A nested Canvas created by flow.group(...)
Flow	An executable calculation made of Nodes and typed connections	A .pxflow document and Canvas
Component package	The optional install and release unit that contributes Components	Internal/test-only V1 diagnostics; third-party activation blocked
Run	One calculation using pinned logic, inputs, and environment	Status, diagnostics, and history
Result	The typed values and artifacts produced by a Run	Result area or a read-only Report position

Inspect an internal/test-only V1 Component contract

The current V1 container accepts one Component declaration and executor entry. The SDK can match an imported companion target to an installed release and store a ComponentRef. Exact ProjectScope data-path isolation is implemented, but that neither binds the request to the authenticated principal's Project permission nor authorizes third-party execution:

Install and preserve a Component target

1. 1Internal/test V1 installExact ProjectScope data path; production authorization is incomplete
2. 2Import companionUse the package-owned Python target
3. 3Resolve exact releaseCreate a live px.Client before flow.node(...)
4. 4Preserve unsupported targetDo not Validate or Run third-party code

Current V1 is Project-isolated at the data layer. Third-party activation stays blocked until Project authorization and execution trust close together.

The successor V2 Components dock projects admitted declarations through host-owned component.declarative@2. V2 settings are declared through component-declared-settings@1, at most eight per declaration. Package renderer/modal/editor fields are not V2; rich surfaces belong only to a later RFC-014 successor. Review the current and planned Component package boundaries.

Read the main states

State	Meaning	Next action
Valid	Required inputs, types, units, and dependencies are ready	Run is available
Draft	A change is waiting for a decision	Apply or Cancel
Running	A pinned Flow revision is executing	Monitor or Cancel
Stale	Report inputs, mappings, or Flow logic changed after the displayed Result	Save and Run again
Partial	Some usable Results completed while other work failed	Review diagnostics and start a new Run if needed
Blocked	A permission, policy, or required input prevents execution	Follow the displayed action

Continue

• Report Workbench
• Report and Flow connections
• PXFLOW Studio
• Author a Flow and Report with Python
• SDK and PXFLOW Studio
• Components and Component packages
• Runs, Results, and recovery