mdtpy 0.2.2__tar.gz → 0.2.3__tar.gz

mdtpy-0.2.3/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: mdtpy
+Version: 0.2.3
+Summary: MDTPlatform을 python 언어를 통해 활용할 수 있는 라이브러리를 제공한다.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: basyx-python-sdk<3.0.0,>=2.0.0
+Requires-Dist: dataclass-wizard<1,>=0.22
+Requires-Dist: isodate>=0.7.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: tika>=3.1.0
+Requires-Dist: typing_extensions>=4.2.0
+Requires-Dist: urllib3<3.0.0,>=2.6.2
+
+# mdtpy
+
+MDT(Manufacturing Digital Twin) 플랫폼을 위한 Python 클라이언트 라이브러리.
+Asset Administration Shell(AAS) 표준을 기반으로 MDT Instance Manager 및 개별
+FA³ST 인스턴스에 HTTP REST로 접근하는 API를 제공한다.
+
+내부적으로 [`basyx-python-sdk`](https://pypi.org/project/basyx-python-sdk/)를
+사용해 AAS 모델(`Property`, `SubmodelElementCollection`, `SubmodelElementList`,
+`File`, `Range`, `MultiLanguageProperty`, `Operation`, `TimeSeries` 등)을 다룬다.
+
+## 요구 사항
+
+- Python 3.10 이상
+- [uv](https://docs.astral.sh/uv/) (의존성/빌드 관리)
+
+## 설치
+
+```bash
+uv sync                  # 런타임 의존성
+make install-dev         # 개발 의존성(pytest)까지 함께 설치
+```
+
+소스 레이아웃은 `src/mdtpy/`이며, `src/`가 Python path에 등록되어 있다
+(`.vscode/settings.json`).
+
+## 빠른 시작
+
+```python
+import mdtpy
+
+# 1. MDT Instance Manager에 접속
+manager = mdtpy.connect("http://localhost:12985/instance-manager")
+
+# 2. 인스턴스 가져오기 / 시작
+instance = manager.instances['my_twin']
+if not instance.is_running():
+    instance.start()
+
+# 3. 파라미터 읽기/쓰기
+param = instance.parameters['Status']
+print(param.read_value())
+param.update_value('Running')
+
+# 4. Operation 호출
+op = instance.operations['Inspect']
+result = op.invoke(Image=instance.parameters['UpperImage'])
+op.output_arguments.update_value(result)
+
+# 5. 시계열 데이터
+ts = instance.timeseries['WelderAmpereLog'].timeseries()
+df = ts.segments['Latest'].records_as_pandas()
+```
+
+상세 사용법은 [`doc/programming_guide.md`](doc/programming_guide.md) 참조.
+
+## 주요 모듈
+
+| 모듈 | 역할 |
+|---|---|
+| `mdtpy.instance` | `connect()`, `MDTInstanceManager`, `MDTInstance`, 컬렉션, 폴러 |
+| `mdtpy.reference` | `ElementReference` 추상화 (`DefaultElementReference`, `LazyElementReference`) |
+| `mdtpy.parameter` | `MDTParameter`, `MDTParameterCollection` |
+| `mdtpy.submodel` | `SubmodelService`, `SubmodelServiceCollection`, `SubmodelElementCollection` |
+| `mdtpy.operation` | `OperationSubmodelService`, `Argument`, `ArgumentList` |
+| `mdtpy.timeseries` | `TimeSeriesService` (pandas 통합) |
+| `mdtpy.value` | SME ↔ Python 값 ↔ 서버 wire JSON 변환 |
+| `mdtpy.descriptor` | 불변 dataclass 디스크립터, semantic_id 기반 분류 |
+| `mdtpy.aas_misc` | AAS wire 포맷 dataclass (`Endpoint`, `OperationVariable` 등) |
+| `mdtpy.fa3st` | 개별 FA³ST 인스턴스용 HTTP 헬퍼 (`call_get`/`call_put`/...) |
+| `mdtpy.http_client` | Instance Manager용 응답 파서, 공통 예외 변환 |
+| `mdtpy.exceptions` | `MDTException` 계층 |
+| `mdtpy.utils` | ISO 8601 / timedelta / SME→Python 변환 헬퍼 |
+| `mdtpy.airflow` | Apache Airflow DAG 통합 (선택, 자동 import되지 않음) |
+| `mdtpy.basyx.serde` | basyx-python-sdk 직렬화 래퍼 |
+
+## 개발
+
+### 테스트 실행
+
+```bash
+make test              # 전체 pytest suite
+make test-cov          # 커버리지 보고서 포함
+```
+
+또는 직접 실행:
+
+```bash
+uv run --env-file .env pytest tests/test_instance.py
+uv run --env-file .env pytest tests/test_instance.py::TestMDTInstanceCollection -v
+```
+
+> **참고**: ROS2(`/opt/ros/humble/...`)를 source한 셸에서는 시스템
+> `launch_pytest` 플러그인이 자동 로드되어 `yaml` 누락으로 충돌한다. `Makefile`
+> 과 `.env`가 `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`을 주입하여 이를 우회한다.
+> ROS가 source되지 않은 셸이라면 `uv run pytest`만으로도 충분하다.
+
+`tests/` 폴더의 단위 테스트는 외부 서버 의존 없이 mock으로 동작한다
+(300+ tests). `src/samples/sample_*.py` 스크립트들은 **실서버 대상 사용 예제 /
+스모크 테스트**이므로 별도 환경에서 실행한다 (예: `python src/samples/sample_reference.py`).
+
+### 코드 스타일
+
+- 코드 주석/docstring: 한국어 (평서문 "~한다")
+- 로깅/예외 메시지: 영어
+- import 순서: `__future__` → `typing` → 표준 → 서드파티 → 로컬
+- 타입 힌트: built-in 우선 (`list`/`dict`/`tuple`), `Optional[X]` 권장
+- 들여쓰기: 4-space
+- 라인 길이: 100자 (신규 코드)
+
+자세한 규칙과 아키텍처는 [`CLAUDE.md`](CLAUDE.md) 참조.
+
+## 빌드
+
+```bash
+uv build               # sdist + wheel을 dist/에 생성
+```

mdtpy-0.2.3/README.md

@@ -0,0 +1,116 @@
+# mdtpy
+
+MDT(Manufacturing Digital Twin) 플랫폼을 위한 Python 클라이언트 라이브러리.
+Asset Administration Shell(AAS) 표준을 기반으로 MDT Instance Manager 및 개별
+FA³ST 인스턴스에 HTTP REST로 접근하는 API를 제공한다.
+
+내부적으로 [`basyx-python-sdk`](https://pypi.org/project/basyx-python-sdk/)를
+사용해 AAS 모델(`Property`, `SubmodelElementCollection`, `SubmodelElementList`,
+`File`, `Range`, `MultiLanguageProperty`, `Operation`, `TimeSeries` 등)을 다룬다.
+
+## 요구 사항
+
+- Python 3.10 이상
+- [uv](https://docs.astral.sh/uv/) (의존성/빌드 관리)
+
+## 설치
+
+```bash
+uv sync                  # 런타임 의존성
+make install-dev         # 개발 의존성(pytest)까지 함께 설치
+```
+
+소스 레이아웃은 `src/mdtpy/`이며, `src/`가 Python path에 등록되어 있다
+(`.vscode/settings.json`).
+
+## 빠른 시작
+
+```python
+import mdtpy
+
+# 1. MDT Instance Manager에 접속
+manager = mdtpy.connect("http://localhost:12985/instance-manager")
+
+# 2. 인스턴스 가져오기 / 시작
+instance = manager.instances['my_twin']
+if not instance.is_running():
+    instance.start()
+
+# 3. 파라미터 읽기/쓰기
+param = instance.parameters['Status']
+print(param.read_value())
+param.update_value('Running')
+
+# 4. Operation 호출
+op = instance.operations['Inspect']
+result = op.invoke(Image=instance.parameters['UpperImage'])
+op.output_arguments.update_value(result)
+
+# 5. 시계열 데이터
+ts = instance.timeseries['WelderAmpereLog'].timeseries()
+df = ts.segments['Latest'].records_as_pandas()
+```
+
+상세 사용법은 [`doc/programming_guide.md`](doc/programming_guide.md) 참조.
+
+## 주요 모듈
+
+| 모듈 | 역할 |
+|---|---|
+| `mdtpy.instance` | `connect()`, `MDTInstanceManager`, `MDTInstance`, 컬렉션, 폴러 |
+| `mdtpy.reference` | `ElementReference` 추상화 (`DefaultElementReference`, `LazyElementReference`) |
+| `mdtpy.parameter` | `MDTParameter`, `MDTParameterCollection` |
+| `mdtpy.submodel` | `SubmodelService`, `SubmodelServiceCollection`, `SubmodelElementCollection` |
+| `mdtpy.operation` | `OperationSubmodelService`, `Argument`, `ArgumentList` |
+| `mdtpy.timeseries` | `TimeSeriesService` (pandas 통합) |
+| `mdtpy.value` | SME ↔ Python 값 ↔ 서버 wire JSON 변환 |
+| `mdtpy.descriptor` | 불변 dataclass 디스크립터, semantic_id 기반 분류 |
+| `mdtpy.aas_misc` | AAS wire 포맷 dataclass (`Endpoint`, `OperationVariable` 등) |
+| `mdtpy.fa3st` | 개별 FA³ST 인스턴스용 HTTP 헬퍼 (`call_get`/`call_put`/...) |
+| `mdtpy.http_client` | Instance Manager용 응답 파서, 공통 예외 변환 |
+| `mdtpy.exceptions` | `MDTException` 계층 |
+| `mdtpy.utils` | ISO 8601 / timedelta / SME→Python 변환 헬퍼 |
+| `mdtpy.airflow` | Apache Airflow DAG 통합 (선택, 자동 import되지 않음) |
+| `mdtpy.basyx.serde` | basyx-python-sdk 직렬화 래퍼 |
+
+## 개발
+
+### 테스트 실행
+
+```bash
+make test              # 전체 pytest suite
+make test-cov          # 커버리지 보고서 포함
+```
+
+또는 직접 실행:
+
+```bash
+uv run --env-file .env pytest tests/test_instance.py
+uv run --env-file .env pytest tests/test_instance.py::TestMDTInstanceCollection -v
+```
+
+> **참고**: ROS2(`/opt/ros/humble/...`)를 source한 셸에서는 시스템
+> `launch_pytest` 플러그인이 자동 로드되어 `yaml` 누락으로 충돌한다. `Makefile`
+> 과 `.env`가 `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`을 주입하여 이를 우회한다.
+> ROS가 source되지 않은 셸이라면 `uv run pytest`만으로도 충분하다.
+
+`tests/` 폴더의 단위 테스트는 외부 서버 의존 없이 mock으로 동작한다
+(300+ tests). `src/samples/sample_*.py` 스크립트들은 **실서버 대상 사용 예제 /
+스모크 테스트**이므로 별도 환경에서 실행한다 (예: `python src/samples/sample_reference.py`).
+
+### 코드 스타일
+
+- 코드 주석/docstring: 한국어 (평서문 "~한다")
+- 로깅/예외 메시지: 영어
+- import 순서: `__future__` → `typing` → 표준 → 서드파티 → 로컬
+- 타입 힌트: built-in 우선 (`list`/`dict`/`tuple`), `Optional[X]` 권장
+- 들여쓰기: 4-space
+- 라인 길이: 100자 (신규 코드)
+
+자세한 규칙과 아키텍처는 [`CLAUDE.md`](CLAUDE.md) 참조.
+
+## 빌드
+
+```bash
+uv build               # sdist + wheel을 dist/에 생성
+```

mdtpy-0.2.3/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mdtpy"
+version = "0.2.3"
+description = "MDTPlatform을 python 언어를 통해 활용할 수 있는 라이브러리를 제공한다."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "basyx-python-sdk>=2.0.0,<3.0.0",
+    "dataclass-wizard>=0.22,<1",
+    "isodate>=0.7.2",
+    "jinja2>=3.1.6",
+    "pandas>=2.3.3",
+    "requests>=2.32.5",
+    "tika>=3.1.0",
+    "typing_extensions>=4.2.0",
+    "urllib3>=2.6.2,<3.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mdtpy*"]
+exclude = ["samples*"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# 참고: ROS2를 source한 쉘에서는 /opt/ros/.../launch_pytest 플러그인이
+# 자동 로드되어 yaml 누락으로 충돌한다. `.env`의 PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
+# 을 uv가 픽업하도록 호출해야 하므로 다음 중 하나를 사용한다.
+#   make test
+#   uv run --env-file .env pytest
+# 또는 셸에 `export UV_ENV_FILE=.env`를 등록하면 `uv run pytest`도 그대로 동작한다.

{mdtpy-0.2.2 → mdtpy-0.2.3}/src/mdtpy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 # SSL 인증서 검증 경고 억제
 import urllib3

mdtpy-0.2.3/src/mdtpy/aas_misc.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Iterable
+from enum import Enum, auto
+
+import json
+import datetime
+from dataclasses import dataclass, field
+from dataclass_wizard import JSONWizard
+
+from basyx.aas import model
+from .basyx import serde as basyx_serde
+from . import utils
+
+
+class SecurityTypeEnum(Enum):
+    """AAS Endpoint의 보안 속성 종류."""
+
+    NONE = auto()
+    RFC_TLSA = auto()
+    W3C_DID = auto()
+
+
+@dataclass(slots=True)
+class SecurityAttributeObject(JSONWizard):
+    """
+    AAS Endpoint에 부여되는 보안 속성 단위.
+
+    Attributes:
+        type (SecurityTypeEnum): 보안 속성 종류.
+        key (str): 속성 키.
+        value (str): 속성 값.
+    """
+    type: SecurityTypeEnum
+    key: str
+    value: str
+
+
+@dataclass(slots=True)
+class ProtocolInformation:
+    """
+    AAS Endpoint의 프로토콜 정보를 나타내는 wire 포맷.
+
+    필드 이름이 camelCase인 것은 서버(JSON) 표기를 그대로 따른 것이다.
+
+    Attributes:
+        href (Optional[str]): 엔드포인트 URL.
+        endpointProtocol (Optional[str]): 프로토콜 이름 (예: "HTTP").
+        endpointProtocolVersion (Optional[str]): 프로토콜 버전 (예: "1.1").
+        subprotocol (Optional[str]): 서브프로토콜 이름.
+        subprotocolBody (Optional[str]): 서브프로토콜 본문.
+        subprotocolBody_encoding (Optional[str]): 서브프로토콜 본문 인코딩.
+        securityAttributes (list[SecurityAttributeObject]): 보안 속성 목록.
+    """
+    href: Optional[str]
+    endpointProtocol: Optional[str] = field(default=None)
+    endpointProtocolVersion: Optional[str] = field(default=None)
+    subprotocol: Optional[str] = field(default=None)
+    subprotocolBody: Optional[str] = field(default=None)
+    subprotocolBody_encoding: Optional[str] = field(default=None)
+    securityAttributes: list[SecurityAttributeObject] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class Endpoint:
+    """
+    AAS Endpoint (interface + protocolInformation 묶음).
+
+    Attributes:
+        interface (str): 인터페이스 식별자 (예: "SUBMODEL").
+        protocolInformation (ProtocolInformation): 접속 프로토콜 정보.
+    """
+    interface: str
+    protocolInformation: ProtocolInformation
+
+
+@dataclass(slots=True)
+class OperationVariable:
+    """
+    AAS Operation의 입력/출력/입출력 변수를 감싸는 컨테이너.
+
+    내부적으로는 basyx의 `model.SubmodelElement`를 그대로 들고 있으며,
+    JSON 변환은 `basyx_serde`에 위임한다.
+
+    Attributes:
+        value (model.SubmodelElement): 변수의 값을 담은 SubmodelElement.
+    """
+    value: model.SubmodelElement
+
+    @classmethod
+    def from_dict(cls, data: dict) -> OperationVariable:
+        """
+        JSON 객체에서 OperationVariable을 만든다.
+
+        Args:
+            data (dict): `{'value': <SubmodelElement JSON>}` 형식의 dict.
+        Returns:
+            OperationVariable: basyx로 역직렬화된 변수 객체.
+        """
+        return cls(value=basyx_serde.from_dict(data['value']))
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        JSON 직렬화 가능한 dict로 변환한다.
+
+        Returns:
+            dict[str, Any]: `{'value': <SubmodelElement JSON dict>}`.
+        """
+        return {'value': json.loads(basyx_serde.to_json(self.value))}
+
+
+@dataclass(slots=True)
+class OperationResult:
+    """
+    AAS Operation 호출 결과.
+
+    Attributes:
+        messages (Optional[list[str]]): 서버가 반환한 메시지 목록.
+        execution_state (str): 실행 상태 ("Completed", "Failed" 등).
+        success (bool): 성공 여부.
+        output_op_variables (Optional[list[OperationVariable]]): 출력 인자 변수.
+        inoutput_op_variables (Optional[list[OperationVariable]]): 입출력 인자 변수.
+    """
+    messages: Optional[list[str]]
+    execution_state: str
+    success: bool
+    output_op_variables: Optional[list[OperationVariable]]
+    inoutput_op_variables: Optional[list[OperationVariable]]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> OperationResult:
+        """
+        서버 JSON 응답에서 OperationResult를 구성한다.
+
+        서버 키 `outputArguments` / `inoutputArguments`를 OperationVariable
+        목록으로 변환한다.
+
+        Args:
+            data (dict): JSON으로 파싱된 응답 본문.
+        Returns:
+            OperationResult: 변환된 결과 객체.
+        """
+        output_arguments = data.get('outputArguments')
+        if output_arguments:
+            output_arguments = [OperationVariable.from_dict(arg) for arg in output_arguments]
+        inoutput_arguments = data.get('inoutputArguments')
+        if inoutput_arguments:
+            inoutput_arguments = [OperationVariable.from_dict(arg) for arg in inoutput_arguments]
+
+        return cls(
+            messages=data.get('messages'),
+            execution_state=data['executionState'],
+            success=data['success'],
+            output_op_variables=output_arguments,
+            inoutput_op_variables=inoutput_arguments,
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> OperationResult:
+        """JSON 문자열로부터 OperationResult를 구성한다."""
+        return cls.from_dict(json.loads(json_str))
+
+
+@dataclass(slots=True)
+class OperationHandle:
+    """
+    비동기 Operation 호출이 반환하는 핸들.
+
+    Attributes:
+        handle_id (str): 서버가 발급한 비동기 작업 식별자.
+    """
+    handle_id: str
+
+    @classmethod
+    def from_json(cls, json_str: str) -> OperationHandle:
+        """
+        JSON 문자열에서 OperationHandle을 만든다.
+
+        서버는 `handleId` 키(camelCase)를 사용하므로 그에 맞춰 매핑한다.
+
+        Args:
+            json_str (str): `{"handleId": "..."}` 형식의 JSON.
+        Returns:
+            OperationHandle: 핸들 객체.
+        """
+        json_dict = json.loads(json_str)
+        return cls(handle_id=json_dict['handleId'])
+
+
+@dataclass(slots=True)
+class OperationRequest:
+    """
+    AAS Operation 호출 요청 본문.
+
+    Attributes:
+        input_arguments (Iterable[OperationVariable]): 입력 인자 변수 목록.
+        inoutput_arguments (Iterable[OperationVariable]): 입출력 인자 변수 목록.
+        client_timeout_duration (datetime.timedelta): 클라이언트 측 타임아웃.
+            JSON 직렬화 시 ISO 8601 duration 문자열로 변환된다.
+    """
+    input_arguments: Iterable[OperationVariable]
+    inoutput_arguments: Iterable[OperationVariable]
+    client_timeout_duration: datetime.timedelta
+
+    def to_json(self) -> str:
+        """
+        요청 본문을 JSON 문자열로 직렬화한다.
+
+        현재 fa3st 서버는 `inputArguments`만 인식하므로 `inoutputArguments`는
+        직렬화에서 제외한다. (필요 시 아래 주석을 해제하여 포함시킬 수 있다.)
+
+        Returns:
+            str: JSON 문자열.
+        """
+        in_opv_list = [op_var.to_dict() for op_var in self.input_arguments]
+        return json.dumps({
+            'inputArguments': in_opv_list,
+            # 'inoutputArguments': [op_var.to_dict() for op_var in self.inoutput_arguments],
+            'clientTimeoutDuration': utils.timedelta_to_iso8601(self.client_timeout_duration),
+        })

mdtpy-0.2.3/src/mdtpy/descriptor.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from typing import Optional
+from dataclasses import dataclass, field
+from enum import Enum
+
+from dataclass_wizard import JSONWizard
+
+
+class MDTInstanceStatus(Enum):
+    """MDTInstance의 생명주기 상태."""
+
+    STOPPED = "STOPPED"
+    STARTING = "STARTING"
+    RUNNING = "RUNNING"
+    STOPPING = "STOPPING"
+    FAILED = "FAILED"
+
+
+class MDTAssetType(Enum):
+    """MDTInstance가 표현하는 자산 종류.
+
+    Note:
+        값이 PascalCase인 것은 서버 응답에 사용되는 표기를 그대로 따른 것이다.
+    """
+
+    Machine = "Machine"
+    Process = "Process"
+    Line = "Line"
+    Factory = "Factory"
+
+
+class AssetKind(Enum):
+    """AAS Asset Kind (instance / type / not-applicable)."""
+
+    INSTANCE = "INSTANCE"
+    NOT_APPLICABLE = "NOT_APPLICABLE"
+    TYPE = "TYPE"
+
+
+@dataclass(frozen=True, slots=True)
+class InstanceDescriptor(JSONWizard):
+    """
+    MDTInstance 등록정보.
+
+    Attributes:
+        id (str): MDTInstance의 고유 식별자.
+        status (MDTInstanceStatus): MDTInstance의 현재 상태.
+        aas_id (str): 연결된 AAS의 ID(URI).
+        base_endpoint (Optional[str]): MDTInstance의 베이스 엔드포인트.
+        aas_id_short (Optional[str]): 연결된 AAS의 idShort.
+        global_asset_id (Optional[str]): 전역 자산 식별자.
+        asset_type (Optional[MDTAssetType]): 자산 종류.
+        asset_kind (Optional[AssetKind]): AAS Asset Kind.
+    """
+    id: str
+    status: MDTInstanceStatus
+    aas_id: str
+    base_endpoint: Optional[str] = field(default=None, hash=False, compare=False)
+    aas_id_short: Optional[str] = field(default=None, hash=False, compare=False)
+    global_asset_id: Optional[str] = field(default=None, hash=False, compare=False)
+    asset_type: Optional[MDTAssetType] = field(default=None, hash=False, compare=False)
+    asset_kind: Optional[AssetKind] = field(default=None, hash=False, compare=False)
+
+
+@dataclass(frozen=True, slots=True)
+class MDTParameterDescriptor(JSONWizard):
+    """
+    MDTParameter 등록정보.
+
+    Attributes:
+        id (str): 파라미터 식별자.
+        value_type (str): 파라미터 값 타입 (XSD 데이터 타입 문자열).
+        reference (str): 파라미터 참조 문자열 (`param:<instance>:<param>` 형태).
+        name (Optional[str]): 사람이 읽는 파라미터 이름.
+        endpoint (Optional[str]): 파라미터 접근 엔드포인트 URL.
+    """
+    id: str
+    value_type: str
+    reference: str
+    name: Optional[str] = None
+    endpoint: Optional[str] = None
+
+
+SEMANTIC_ID_INFOR_MODEL_SUBMODEL = "https://etri.re.kr/mdt/Submodel/InformationModel/1/1"
+SEMANTIC_ID_AI_SUBMODEL = "https://etri.re.kr/mdt/Submodel/AI/1/1"
+SEMANTIC_ID_SIMULATION_SUBMODEL = "https://etri.re.kr/mdt/Submodel/Simulation/1/1"
+SEMANTIC_ID_DATA_SUBMODEL = "https://etri.re.kr/mdt/Submodel/Data/1/1"
+SEMANTIC_ID_TIME_SERIES_SUBMODEL = "https://admin-shell.io/idta/TimeSeries/1/1"
+
+
+@dataclass(frozen=True, slots=True)
+class MDTSubmodelDescriptor(JSONWizard):
+    """
+    MDTSubmodel 등록정보.
+
+    semantic_id 값에 따라 InformationModel / Data / Simulation / AI / TimeSeries
+    중 하나로 분류된다. 분류는 `is_*()` 메서드로 확인한다.
+
+    Attributes:
+        id (str): 서브모델 식별자(URI).
+        id_short (str): 서브모델 idShort.
+        semantic_id (str): 서브모델 semantic id (URI).
+        endpoint (Optional[str]): 서브모델 접근 엔드포인트 URL.
+    """
+    id: str
+    id_short: str
+    semantic_id: str
+    endpoint: Optional[str]
+
+    def is_information_model(self) -> bool:
+        """semantic_id가 Information Model에 해당하면 True를 반환한다."""
+        return self.semantic_id == SEMANTIC_ID_INFOR_MODEL_SUBMODEL
+
+    def is_data(self) -> bool:
+        """semantic_id가 Data Model에 해당하면 True를 반환한다."""
+        return self.semantic_id == SEMANTIC_ID_DATA_SUBMODEL
+
+    def is_simulation(self) -> bool:
+        """semantic_id가 Simulation Model에 해당하면 True를 반환한다."""
+        return self.semantic_id == SEMANTIC_ID_SIMULATION_SUBMODEL
+
+    def is_ai(self) -> bool:
+        """semantic_id가 AI Model에 해당하면 True를 반환한다."""
+        return self.semantic_id == SEMANTIC_ID_AI_SUBMODEL
+
+    def is_time_series(self) -> bool:
+        """semantic_id가 Time Series Model에 해당하면 True를 반환한다."""
+        return self.semantic_id == SEMANTIC_ID_TIME_SERIES_SUBMODEL
+
+
+@dataclass(frozen=True, slots=True)
+class ArgumentDescriptor(JSONWizard):
+    """
+    Operation 인자(input / inout / output) 등록정보.
+
+    Attributes:
+        id (str): 인자 식별자.
+        id_short_path (str): 서브모델 내 인자의 idShort 경로
+            (예: `Inputs.Speed`, `Out.Result[0]`).
+        value_type (str): 인자 값 타입 (XSD 데이터 타입 문자열).
+        reference (str): 인자 참조 문자열
+            (`oparg:<instance>:<op>:in|out:<arg>` 형태).
+    """
+    id: str
+    id_short_path: str
+    value_type: str
+    reference: str
+
+
+@dataclass(frozen=True, slots=True)
+class MDTOperationDescriptor(JSONWizard):
+    """
+    MDTOperation 등록정보.
+
+    Attributes:
+        id (str): 연산 식별자.
+        operation_type (str): 연산 타입 (예: "sync", "async").
+        input_arguments (list[ArgumentDescriptor]): 입력 인자 목록.
+        output_arguments (list[ArgumentDescriptor]): 출력 인자 목록.
+    """
+    id: str
+    operation_type: str
+    input_arguments: list[ArgumentDescriptor]
+    output_arguments: list[ArgumentDescriptor]