실행과 결과 API

px.Client는 저장된 Flow를 실행해 Run과 Result를 만듭니다. Report 없이 Flow만 실행할 때는 Flow와 input을 직접 전달합니다. Report에서 연결한 Flow를 실행할 때는 저장한 connection을 전달하며, 이 경우 Report에 작성한 input 연결과 결과 위치가 함께 적용됩니다.

일반 Python에서는 px.Client(...)로 실행 범위를 만든 뒤 client.run(...)처럼 호출합니다. 이 구조에서 px.Client(...)는 SDK 생성자이고 client.run(...)은 만들어진 Client 객체의 메서드입니다. PipelineXLab이 호스팅하는 surface도 px.Client(workspace="...", project="...")로 범위를 명시합니다. lowercase px.client()는 host scope 주입을 검토할 후속 계약에 예약돼 있으며 현재 facade에는 없습니다.

from pipelinexlab import px
from project_flows.girder_check import flow
from project_reports.girder_review import strength, strength_cases, serviceability

client = px.Client(workspace="engineering", project="bridge_project")

direct_run = client.run(flow, span=12.0, demand=860.0)
report_run = client.run(strength)
runs = client.run_many([
    strength,
    serviceability,
])
cases = [
    {"case_key": "uls_01", "span": 12.0, "demand": 860.0},
    {"case_key": "uls_02", "span": 12.0, "demand": 920.0},
]
batch = client.run_batch(
    strength_cases,
    cases,
    case_key="case_key",
    inputs={
        "span": flow.inputs.span,
        "demand": flow.inputs.demand,
    },
    result_mapping="case_check_to_results",
)

위 예제의 strength, strength_cases와 serviceability는 Report 작성 파일에서 report.connect_flow(...)이 반환하고 report.save()로 저장한 connection입니다. strength_cases의 case input port에는 saved input mapping을 두지 않고 inputs에서 case field와 Flow input을 연결합니다.

Client 객체 만들기

• SDK 생성자 · px.Client(...)로 실행할 Project 범위 선택하기

SDK와 Runtime 버전 호환성

px.Client(...)는 첫 연결에서 SDK와 Runtime이 지원하는 wire-release 범위를 교환하고, 두 범위에 포함되는 가장 높은 버전을 선택합니다. diagnostic registry 버전은 별도로 일치해야 합니다. 지원 범위가 겹치지 않으면 px.Error의 Diagnostic.code가 PX_RUNTIME_INCOMPATIBLE이며, params.actualVersion과 params.supportedVersion에서 제시된 버전과 필요한 범위를 확인할 수 있습니다. px.diagnose()는 기존처럼 Runtime에 접속할 수 있는지 확인합니다.

wire-release의 시작 버전은 0.1.0입니다. native binding을 초기화하는 core ABI 버전과 배포 패키지 버전은 각각 별도 계약입니다. wire 협상을 추가해도 공개 배포 seal은 유지되며, 미출시 패키지 버전 0.0.0이 바뀌지 않습니다. 정확한 요청·응답과 범위 규칙은 SDK 배포 계약의 commercializationSeats.versionSkew.negotiation을 따릅니다.

Report payload 전송 상한

px.Client(...)의 payloadTransfer 협상은 같은 transfer wire v1에서 서버가 광고한 maxPayloadBytes·chunkMaxBytes와 SDK 상한(각각 32 MiB·65,536 bytes) 중 작은 값을 선택합니다. 전체 요청·응답은 inline과 chunk 전송 모두 선택된 payload 상한을 지키며, 업로드·다운로드 chunk는 선택된 chunk 상한을 지킵니다. 서버 상한이 늘어도 SDK 상한은 늘지 않습니다. 각 frame의 1,048,576-byte 방어와 정수 배열·SHA-256 검증도 유지됩니다.

cap은 양의 정수여야 합니다(boolean·실수·문자열 불가). descriptor는 version: 1, operation: "product.runtime.transfer", 두 cap을 필수로 가지며, 선택적 maxRetainedBytes도 양의 정수입니다. 다른 멤버·지원하지 않는 version·잘못된 operation 또는 cap은 PX_RUNTIME_INCOMPATIBLE로 연결을 닫습니다. capability 자체가 없거나 null·빈 객체인 경우에만 기존 frame 제한 전송을 사용합니다. 실패한 협상을 재시도하여 기능 없는 연결로 바꾸지 않습니다.

wire v1 read 요청의 선택적 maxBytes는 양의 정수 상한입니다. Runtime은 서버 chunk 상한·maxBytes·남은 bytes 중 최소 길이를 반환합니다. SDK는 서버 chunk 상한이 선택된 상한보다 큰 경우에만 이를 보내므로 기존 65,536-byte 서버의 요청 형태는 유지됩니다. 상한을 넘기는 응답 또는 maxBytes를 거부하는 서버는 명시적으로 실패하며 재시도하지 않습니다. 정확한 규칙은 authoring 계약의 runtime.payloadTransfer를 따릅니다.

Client 객체 메서드

client = px.Client(...)로 만든 객체에서 호출합니다.

• .run()으로 Flow를 input과 직접 실행하거나 connection 하나 실행하기
• .run_many()로 선택한 여러 connection을 독립 Run으로 시작하기
• .run_batch()로 connection 하나를 여러 scalar case로 반복 실행하기

어떤 실행 API를 선택하나요?

필요한 실행	API	만들어지는 실행
Report 없이 Flow 한 번	client.run(flow, **inputs)	Flow Run 1개
Report의 Connected Flow 하나	client.run(connection)	Flow Run 1개
선택한 Connected Flow 여러 개	client.run_many(connections)	connection별 Flow Run
같은 connection의 N개 scalar case	client.run_batch(..., inputs=..., result_mapping=...)	case별 Run N개
current list[T] input 하나	client.run(flow, **inputs) 또는 client.run(connection)	목록 전체를 받는 Run 1개

계획된 px.Table[RecordType]도 collection 하나를 Run 하나에 전달한다는 의미 계약은 보존하지만, px.Table과 decorator @px.record는 현재 public facade에 없는 contract_only 이름이므로 current 실행 타입처럼 사용하지 않습니다. record schema의 current 문법은 px.Record subclass의 annotated field입니다.

여러 Flow와 같은 Flow의 여러 connection

client.run_many(...)는 전달한 connection마다 독립 Run을 만듭니다. 서로 다른 Flow를 가리킬 수 있고, 같은 Flow를 서로 다른 connection key로 여러 번 연결해 실행할 수도 있습니다. 각 connection의 input 연결, 결과 위치, 재실행 필요 상태와 Run 이력은 따로 유지됩니다.

Runtime은 Project의 resource·license 정책이 정한 동시 실행 한도 안에서 Run을 병렬로 처리합니다. Run의 시작·완료 순서는 계산 dependency를 뜻하지 않습니다.

Flow 사이에 실행 순서가 있을 때

Flow B가 Flow A의 결과를 사용하면 상위 Flow에서 두 단계를 Node 또는 Subflow로 연결합니다. Report에는 그 상위 Flow connection 하나를 추가합니다. Runtime은 상위 Flow 안의 연결선을 실행 순서로 사용합니다.

Project Activity는 한 사용자 동작에서 시작된 Run을 모아 보여 주는 화면입니다. 각 Run은 독립된 상태, 취소, 재시도와 Result를 유지합니다.

Result 확인

각 실행 API는 시작한 Run 또는 Run 묶음을 추적하는 객체를 반환합니다. 이 객체에서 진행 상태를 확인하고, 완료된 Run의 변경되지 않는 Result와 실행 근거를 읽습니다. 이전 Run도 이력에 남으며 Report의 결과 위치에는 사용자가 마지막으로 시작한 실행의 결과가 표시됩니다.

전체 예제

Python으로 Report와 Flow 함께 만들기에서 Report connection 작성부터 단일 Run, 여러 connection과 Batch 선택 기준까지 확인하세요.