SDK·Component 개발 개요
현재 Component 경계
현재 @px.component의 책임은 process-local companion metadata와 Python annotation 기반 port shape 등록까지입니다. current internal/test resolver primitive는 live px.Client를 통해 exact ComponentRef를 저장할 수 있지만 production third-party admission이 아닙니다. 현재 V1의 기존 presentation·settings wire는 호환을 위해 보존하고, 이미 저장된 exact Component target은 production Flow reader에서 read-only unsupported로 표시됩니다. 신규 install·placement·activation의 exact ProjectScope data-path isolation은 구현됐지만 제품 노출은 Project authorization과 execution-trust closure가 닫힌 뒤에만 엽니다. 후속 V2 Canvas는 package UI를 마운트하지 않고 host-owned component.declarative@2만 사용합니다. settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그리며, rich surface는 RFC-016이 소유하는 component-rich-surface-declaration@1 범위이고, bridge는 Node context 읽기와 settings 제안까지만 허용합니다.
모든 Python 파일은 다음 import로 시작합니다.
from pipelinexlab import pxSDK 이름을 구분하는 원칙
PipelineXLab이 제공하는 생성자, 타입과 decorator에는 px.를 붙입니다. 현재 facade는 px.Flow, px.Report, px.Client, px.Results, px.Record, px.Settings, @px.function, @px.component와 marker px.input(...), px.result(...), px.setting(...)을 제공합니다. px.Table, decorator @px.record, px.field(...)는 별도 contract_only 문법입니다.
px.Flow(...)가 반환한 flow처럼 이미 만든 객체의 작업은 그 객체에서 시작합니다.
from pipelinexlab import px
from structural_checks.functions import girder_resistance
flow = px.Flow(
"girder_review",
label="Girder review",
description="Checks one girder design.",
)
span = flow.input("span", float, unit="m", description="Clear span.")
check = flow.node("strength_check", girder_resistance)
flow.connect(span, check.inputs.span)
flow.result("utilization", check.results.utilization)같은 원칙으로 report = px.Report(...)로 만든 Report 객체는 .section()과 .connect_flow()를, 그 결과로 받은 Connected Flow handle은 .bind()와 .show()를 사용합니다. client = px.Client(workspace="engineering", project="bridge_project")로 만든 실행 객체는 .run()을 사용합니다. Node 배치, 연결과 실행을 소유 객체가 보이지 않는 px.* 전역 API로 작성하지 않습니다.
설치한 Function·Flow는 그 package의 public module에서 일반 Python 이름으로 import합니다. third-party Component도 package public symbol을 쓰도록 계약하지만 아래 코드는 post-closure 제품 경로를 설명하는 contract_only 예제입니다. current internal/test resolver primitive를 사용하라는 production 절차가 아닙니다.
이 예제는 contract_only이며 현재 SDK에서 실행할 수 없습니다.
from midas_civil.components import model_viewer
viewer = flow.node("model_viewer", model_viewer) # contract_only: post-closure product path현재 hosted surface를 포함한 모든 공개 Python 호출은 px.Client(workspace="engineering", project="bridge_project")처럼 workspace와 Project를 명시합니다. host가 범위를 주입하는 px.client() convenience는 계획 계약입니다. 전체 이름 목록은 Python SDK API reference에서 확인할 수 있습니다.
Canvas에서 실행할 계산은 현재 Project에서 한 번만 사용하더라도 @px.function(key=..., version=..., description=...)으로 정의합니다. 일반 Python def는 Function 또는 Component body가 호출하는 내부 helper로 사용하며 flow.node(...) target으로 전달하지 않습니다. 설치된 Component와 맞출 companion target은 @px.component(key=..., label=..., description=...)으로 등록합니다. 후속 V2 Canvas UI는 host-owned component.declarative@2 projection만 사용합니다.
현재 decorator는 definition metadata와 annotation 기반 port shape를 등록합니다. nodeKey, layout과 wiring은 placement가 소유합니다. 현재 production의 새 Node placement는 Function target에 대해 다음 한 줄을 사용합니다. 같은 spelling의 Component placement 제품 경로는 두 P0 closure 뒤에만 노출되며 V2 host projection은 admitted declaration만 소비합니다.
node = flow.node("node_key", target)input/result 관계는 placement keyword로 숨기지 않고 모두 명시합니다.
flow.connect(flow_input, node.inputs.value)
flow.result("result_key", node.results.value)한 .py Flow module은 top-level public flow = px.Flow("flow_key", ...) object를 정확히 하나 export합니다. 복잡한 Flow도 큰 decorated function으로 감싸지 않고 Node placement와 connection을 top-level declarative composition으로 유지합니다.
현재 target과 successor target을 구분합니다
| 시점과 작성 상태 | flow.node(...) 뒤 Canvas 표현 | 재사용 규칙 |
|---|---|---|
current · @px.function(key=..., ...) definition | read-only Function Reference Node | Definitions에서 version·사용처별 관리 |
| current · 이미 저장된 exact Component target | 기존 ComponentRef를 read-only unsupported로 보존 | 신규 install·placement·activation 없음 |
post-closure successor · admitted @px.component target | 새 exact ComponentRef | V2 Canvas는 host-owned component.declarative@2만 사용 |
일반 Python def는 Function·Component 내부 helper이므로 Canvas에 별도 Node로 나타나지 않습니다. Project가 소유한 Function은 Definitions → Functions → Open Function에서 source를 엽니다. Function을 변경하면 모든 사용 중인 Node를 먼저 보여 주고 승인한 사용처를 함께 갱신합니다. 한 Node만 다른 계산을 사용해야 하면 Function을 Clone / branch한 뒤 그 Node의 참조만 새 Function으로 바꿉니다.
다른 module의 exported flow object는 Node target이 아닙니다. flow.subflow("subflow_key", imported_flow)로 배치하고 caller에서는 읽기 전용으로 엽니다. 같은 Flow의 flow.group(...)은 presentation membership만 선언하며 실행 구조나 연결을 바꾸지 않습니다.
Extension 전용 decorator는 해당 Extension의 template이나 schema definition을 등록합니다. @px.app은 app surface definition이고 @px.record는 data schema입니다. 현재 Function 실행 target은 flow.node(...)로 배치할 때 Canvas Node가 생깁니다. Component는 저장된 exact target 복구만 current이고 신규 제품 placement는 post-closure successor입니다.
표준 용어
| 용어 | 어디에서 보이는가 | 의미 |
|---|---|---|
| Function | SDK 코드, Project Definitions와 Node 상세 | typed input을 받아 named result를 만드는 재사용 실행 definition |
| Component | read-only discovery; Components dock은 계획 | package가 제공하는 reusable target 계약 |
| Node | PXFLOW Studio Canvas | current Function placement 또는 저장된 unsupported Component target |
| Flow | SDK 코드, PXFLOW Studio와 .pxflow | Node, connection, Flow input/result를 묶은 실행 흐름 |
| Group | PXFLOW Studio Canvas | 같은 Flow Node의 presentation membership |
| External Flow | PXFLOW Studio Canvas | 다른 module의 exported flow object를 배치한 read-only nested Flow |
| Port | Function·Component 상세와 Node 연결점 | 값을 받거나 내보내는 typed 연결점 |
| Run | Project Activity와 실행 이력 | 고정된 Flow revision과 input으로 수행한 한 번의 실행 |
ResultSnapshot | Result panel과 결과 이력 | 어느 Run에서 나왔는지 확인할 수 있는 변경 불가능한 결과 |
Component는 definition 이름입니다. current production은 이미 저장된 durable Component Node target만 read-only unsupported로 표시합니다. 새 flow.node(...) Component placement를 제품에 노출하는 시점은 두 P0 closure 뒤입니다.
전체 연결 구조
flow.group(...)은 같은 Flow의 Canvas 표현만 묶고, flow.subflow(...)는 별도 module에서 가져온 Flow를 read-only External Flow로 배치합니다.
개발자가 제공하는 것
재사용 Function 또는 Component release는 다음 요소를 갖습니다.
- Function이면
@px.function(key=..., version=..., description=...)의 stablefunctionKey와 semantic version - 현재 Component companion이면
@px.component(key=..., ...)의 stablecomponentKey, Category/Subcategory와 annotation 기반 port shape - V2 Canvas presentation은 host-owned
component.declarative@2; settings는component-declared-settings@1· 선언당 최대 8개 - target과 각 port의 canonical
description px.input(...)parameter와px.result(...)result schema- 구조화 값이 있으면
@px.record(...),px.field(...)와px.Table[RecordType] - type, shape, unit과 constraints
- 외부 연결 가능 여부
connection - deterministic/cache 성격과 side-effect policy
files,network,secrets,gpucapability 상한- dependency lock과 재현 가능한 build 정보
- 성공·실패·취소·경계값 test fixture
현재 production authoring에는 Function 항목을 적용합니다. Component release 항목은 companion metadata 작성과 post-closure 계약 검토에 사용하며, 현재 third-party 설치·배치·활성화 절차가 아닙니다.
Flow module은 별도로 stable flowKey, Flow input/result와 모든 connection을 명시합니다. layout은 Canvas presentation state가 소유합니다.
Package, Function version과 capability
| 개념 | 답하는 질문 | 예시 |
|---|---|---|
| package version | 어떤 배포 묶음인가? | bridge-checks 2.3.0 |
| Function version | input/result와 계산 의미가 어떤 버전인가? | girder_resistance 1.1.0 |
| runtime capability | 실행할 때 무엇을 허용해야 하는가? | filesystem read, outbound network, secret, GPU |
package version과 Function version을 독립적으로 관리합니다. Runtime은 capability 상한과 별도로 호출자 권한과 Project policy를 검사합니다.
작성에서 실행까지
아래 흐름에서 Function definition·배치·실행은 current 경로입니다. Component의 exact release 설치·resolve·신규 배치·activation 단계는 구현된 exact ProjectScope data-path isolation에 Project authorization과 execution-trust closure를 더한 post-closure successor에만 해당합니다. current internal/test primitive의 존재가 이 제품 경로를 여는 것은 아닙니다.
등록, import와 Flow materialization은 target body를 실행하지 않습니다.
Port 공개 규칙
- 현재 target parameter annotation은 Node input port입니다.
- 현재
px.Resultsannotated field는 Node result port입니다. flow.input(...)과flow.result(...)는 Flow boundary를 직접 선언합니다.@px.record와px.field(...)는 port가 전달하는 data schema입니다.connection=False는 일반 picker에서 숨기지만 같은 Flow의 explicit connection에는 쓸 수 있습니다.- 읽기·쓰기·실행·공유 권한은
connection과 분리된 ACL에서 관리합니다.
작성한 정보가 보이는 곳
| 위치 | 개발자가 확인할 내용 | 사용자에게 보이는 결과 |
|---|---|---|
| SDK 코드 | definition key, version과 annotation 기반 input/result | target 이름과 설명 |
| Project Definitions → Functions | current Function metadata | 검색·배치 가능한 Function |
| Component recovery discovery | current read-only metadata; Components dock은 계획 | 저장된 exact Component metadata와 unsupported target |
| PXFLOW Studio Canvas | explicit Node key와 connection | 읽기 쉬운 Node와 연결 |
| V2 host Component projection · 계획 | exact identity와 declared input/result | 공통 Node shell·Port |
| AI와 MCP | 화면과 같은 key, description과 제약 | 정확한 검색·설명·실행 제안 |
| 실행 이력 | version, 상태, 오류와 provenance | 다시 확인하고 비교할 수 있는 Run |
권장 개발 순서
- current production 계산은 표준 Function을 고릅니다. Component companion target은 metadata와 post-closure 계약 검토용이며 신규 third-party placement 절차가 아닙니다. V2 Canvas UI는 host-owned
component.declarative@2만 사용하고 rich UI는 RFC-016의component-rich-surface-declaration@1이 소유합니다. 일반 Pythondef는 target 내부 helper로만 사용합니다. - input/result key, type, shape와 unit을 먼저 고정합니다.
- reusable definition의 version과 description을 작성합니다.
- side effect와 필요한 capability를 선언합니다.
- 한 module에 exported
flowobject 하나를 만들고 current Function Node를 배치합니다. - 모든 input/result 관계를
flow.connect(...)와flow.result(...)로 명시합니다. - 같은 Flow의 시각적 묶음만
flow.group(...)으로 추가합니다. - 별도 Flow는 exported object를 import해
flow.subflow(...)로 배치합니다. - unit, boundary, failure와 determinism test를 작성합니다.
- package와 Flow contract 검사를 통과한 release만 공개합니다.