From ddcd90d0502289730203deb8da71f422fc917047 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Sat, 17 Oct 2026 05:58:04 +0000 Subject: [PATCH] docs: restore Task Program API cross-reference links --- .../embodichain.lab.task_program.compiler.rst | 11 +- ...odichain.lab.task_program.integrations.rst | 92 +++++++++- ...b.task_program.integrations.simulation.rst | 2 +- .../embodichain.lab.task_program.language.rst | 15 +- .../embodichain.lab.task_program.rst | 166 +++++++++++++++++- .../embodichain.lab.task_program.runtime.rst | 2 +- ...embodichain.lab.task_program.semantics.rst | 83 ++++++++- embodichain/agents/mllm/task_program.py | 8 +- 8 files changed, 368 insertions(+), 11 deletions(-) diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst index 67ce0fc65..e872431a2 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.compiler.rst @@ -3,7 +3,7 @@ embodichain.lab.task_program.compiler .. automodule:: embodichain.lab.task_program.compiler :members: - :no-index: + :undoc-members: The compiler expands a validated AST into immutable segments and calls. Semantic lowering is provider-independent; live planning starts only after @@ -26,3 +26,12 @@ embodichain.lab.task_program.compiler CompiledTaskProgramValidator TaskProgramCompileError TaskProgramCompiler + +Validator type aliases +---------------------- + +.. currentmodule:: embodichain.lab.task_program.compiler + +These aliases describe the compiled validator variants. + +.. autodata:: CompiledTaskProgramValidator diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst index 5d6be4f29..d71e9a853 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.rst @@ -3,7 +3,26 @@ embodichain.lab.task_program.integrations .. automodule:: embodichain.lab.task_program.integrations :members: - :no-index: + :undoc-members: + :exclude-members: TaskProgramEnvironmentAdapter, TaskProgramAdapterFactory, + TaskProgramEnvironmentFactory, TaskProgramRuntimeAssembly, + PlanningObservationPort, TaskProgramIntegrationCatalog, + SimulationTaskProgramRegistration, IntegrationFingerprintMismatch, + ControlPartEvidenceProviderDeclaration, ControlPartEvidenceProviderFactory, + RegisteredSemanticLowererDeclaration, RegisteredSemanticLowererFactory, + EndpointAdapterDeclaration, RuntimeTransportDeclaration, + ParallelSafetyDeclaration, ParallelCommandSafetyValidatorFactory, + StandardExtensionDeclarations, VersionedKey, default_simulation_settle_presets, + SimulationSceneBinding, SimulationRigidObjectBinding, + SimulationRigidizedArticulationObjectBinding, SimulationArticulationBinding, + SimulationArticulationLinkBinding, AntipodalGraspAffordanceBinding, + RigidizedArticulationAntipodalGraspBinding, ContainerAffordanceBinding, + SupportSurfaceAffordanceBinding, ControlPartCommandPreset, + ControlPartEndpointBinding, ControlPartResourceBinding, + SimulationRobotSkillProfileBinding, SimulationTaskProgramFactory, + SimulationTaskProgramAdapterFactory, ConfiguredHandOverPoseProvider, + CuroboParallelCommandSafetyValidator, CuroboParallelSafetyValidatorFactory, + SimulationSegmentPolicyPort, create_simulation_task_program_adapter .. autosummary:: @@ -117,42 +136,111 @@ Registration and extensions Simulation bindings ------------------- +.. Register shared implementation names once beside their public definitions. + Re-export packages can then index their own names without duplicate + canonical registrations for the same implementation. + +.. py:class:: SimulationSceneBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationSceneBinding :members: +.. py:class:: SimulationRigidObjectBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationRigidObjectBinding :members: +.. py:class:: SimulationRigidizedArticulationObjectBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationRigidizedArticulationObjectBinding :members: +.. py:class:: SimulationArticulationBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationArticulationBinding :members: +.. py:class:: SimulationArticulationLinkBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationArticulationLinkBinding :members: +.. py:class:: AntipodalGraspAffordanceBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: AntipodalGraspAffordanceBinding :members: +.. py:class:: RigidizedArticulationAntipodalGraspBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: RigidizedArticulationAntipodalGraspBinding :members: +.. py:class:: ContainerAffordanceBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: ContainerAffordanceBinding :members: +.. py:class:: SupportSurfaceAffordanceBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SupportSurfaceAffordanceBinding :members: +.. py:class:: ControlPartCommandPreset + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: ControlPartCommandPreset :members: +.. py:class:: ControlPartEndpointBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: ControlPartEndpointBinding :members: +.. py:class:: ControlPartResourceBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: ControlPartResourceBinding :members: +.. py:class:: SimulationRobotSkillProfileBinding + :module: embodichain.lab.task_program.integrations.simulation.bindings + :no-typesetting: + :no-index-entry: + .. autoclass:: SimulationRobotSkillProfileBinding :members: @@ -229,3 +317,5 @@ Implementation module exports .. autofunction:: declare_runtime_transport .. autofunction:: validate_immutable_extension_declaration + +.. autodata:: VersionedKey diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst index a1bebdcb6..d5029e66f 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.integrations.simulation.rst @@ -3,7 +3,7 @@ embodichain.lab.task_program.integrations.simulation .. automodule:: embodichain.lab.task_program.integrations.simulation :members: - :no-index: + :undoc-members: These immutable declarations bind canonical Task Program scene and robot contracts to explicitly selected simulation entities and control parts. diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst index 041e55f01..3f9e0b367 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.language.rst @@ -3,7 +3,7 @@ embodichain.lab.task_program.language .. automodule:: embodichain.lab.task_program.language :members: - :no-index: + :undoc-members: Task Program source is represented by executable-free schema values. The same package owns strict JSON/YAML decoding, reference validation, bounded @@ -42,3 +42,16 @@ embodichain.lab.task_program.language parse_task_program_json render_config_path validate_task_program + +Configuration paths and reference roles +--------------------------------------- + +.. currentmodule:: embodichain.lab.task_program.language + +These exported values describe configuration paths and reference categories. + +.. autodata:: ConfigPath + +.. autodata:: ConfigPathPart + +.. autodata:: SceneReferenceRole diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst index 6525379eb..d285402ec 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.rst @@ -3,7 +3,18 @@ embodichain.lab.task_program .. automodule:: embodichain.lab.task_program :members: - :no-index: + :undoc-members: + :exclude-members: TaskProgramCfg, TaskProgramIntegrationCfg, PoseCfg, TargetRefCfg, + CyclicPoseTargetCfg, PickCfg, PlaceCfg, HandOverCfg, RegisteredSemanticCallCfg, + InvokeCfg, SequenceCfg, RepeatCfg, SegmentCfg, ParallelCfg, BarrierCfg, + WaitStablePostCfg, ObjectNearTargetValidatorCfg, ObjectLiftedValidatorCfg, + ObjectRelativePositionValidatorCfg, ObjectUprightValidatorCfg, + ArticulationJointPositionValidatorCfg, load_task_program, loads_task_program_json, + parse_task_program_json, decode_task_program, validate_task_program, + render_config_path, ConfigPath, ConfigPathPart, SceneReferenceRole, + TaskProgramValidationContext, TaskProgramConfigError, TaskProgramDecodeError, + TaskProgramValidationError, TaskProgramCompiler, CompiledTaskProgram, + TaskProgramCompileError .. autosummary:: @@ -47,57 +58,175 @@ embodichain.lab.task_program Schema ------ +.. Register shared implementation names once beside their public definitions. + Re-export packages can then index their own names without duplicate + canonical registrations for the same implementation. + +.. py:class:: TaskProgramCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramCfg :members: +.. py:class:: TaskProgramIntegrationCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramIntegrationCfg :members: +.. py:class:: PoseCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: PoseCfg :members: +.. py:class:: TargetRefCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: TargetRefCfg :members: +.. py:class:: CyclicPoseTargetCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: CyclicPoseTargetCfg :members: +.. py:class:: PickCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: PickCfg :members: +.. py:class:: PlaceCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: PlaceCfg :members: +.. py:class:: HandOverCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: HandOverCfg :members: +.. py:class:: RegisteredSemanticCallCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: RegisteredSemanticCallCfg :members: +.. py:class:: InvokeCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: InvokeCfg :members: +.. py:class:: SequenceCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: SequenceCfg :members: +.. py:class:: RepeatCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: RepeatCfg :members: +.. py:class:: SegmentCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: SegmentCfg :members: +.. py:class:: ParallelCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: ParallelCfg :members: +.. py:class:: BarrierCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: BarrierCfg :members: +.. py:class:: WaitStablePostCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: WaitStablePostCfg :members: +.. py:class:: ObjectNearTargetValidatorCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: ObjectNearTargetValidatorCfg :members: +.. py:class:: ObjectLiftedValidatorCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + +.. autoclass:: ObjectLiftedValidatorCfg + :members: + +.. py:class:: ObjectRelativePositionValidatorCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + +.. autoclass:: ObjectRelativePositionValidatorCfg + :members: + +.. py:class:: ObjectUprightValidatorCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + +.. autoclass:: ObjectUprightValidatorCfg + :members: + +.. py:class:: ArticulationJointPositionValidatorCfg + :module: embodichain.lab.task_program.language.schema + :no-typesetting: + :no-index-entry: + .. autoclass:: ArticulationJointPositionValidatorCfg :members: @@ -122,12 +251,32 @@ Loading and validation .. autodata:: SceneReferenceRole +.. py:class:: TaskProgramValidationContext + :module: embodichain.lab.task_program.language.decoder + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramValidationContext +.. py:class:: TaskProgramConfigError + :module: embodichain.lab.task_program.language.decoder + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramConfigError +.. py:class:: TaskProgramDecodeError + :module: embodichain.lab.task_program.language.decoder + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramDecodeError +.. py:class:: TaskProgramValidationError + :module: embodichain.lab.task_program.language.decoder + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramValidationError Compilation @@ -137,12 +286,27 @@ Compilation is provider-independent. Environment and simulator binding is documented under :mod:`embodichain.lab.task_program.integrations`; the final Gym lifecycle bridge is :mod:`embodichain.lab.gym.envs.task_program`. +.. py:class:: TaskProgramCompiler + :module: embodichain.lab.task_program.compiler.program + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramCompiler :members: +.. py:class:: CompiledTaskProgram + :module: embodichain.lab.task_program.compiler.program + :no-typesetting: + :no-index-entry: + .. autoclass:: CompiledTaskProgram :members: +.. py:class:: TaskProgramCompileError + :module: embodichain.lab.task_program.compiler.program + :no-typesetting: + :no-index-entry: + .. autoclass:: TaskProgramCompileError Expansion integration diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst index aa921bd6e..762467d35 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.runtime.rst @@ -3,7 +3,7 @@ embodichain.lab.task_program.runtime .. automodule:: embodichain.lab.task_program.runtime :members: - :no-index: + :undoc-members: Runtime services execute lowered Semantic Calls and synchronize parallel branches. They do not own Gym episode lifecycle, ``env.step()``, or diff --git a/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst b/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst index fc3b09014..ce611b9c4 100644 --- a/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst +++ b/docs/source/api_reference/embodichain/embodichain.lab.task_program.semantics.rst @@ -3,7 +3,34 @@ embodichain.lab.task_program.semantics .. automodule:: embodichain.lab.task_program.semantics :members: - :no-index: + :undoc-members: + :exclude-members: SemanticCallSpec, SemanticPose, Pick, Place, HandOver, + RegisteredSemanticCall, SemanticCallDescriptor, SemanticCallCatalog, + builtin_semantic_call_catalog, SceneEntityManifest, SceneManifest, + SemanticIntegrationManifest, SemanticDiagnostic, SemanticValidationError, + RobotSkillProfile, BoundRobotSkillProfile, RobotResource, ResourceEndpoint, + ResourceEndpointAdapter, EndpointResolution, ControlPartEndpoint, + ControlPartEndpointAdapter, ResourceBinding, ResolvedResourceEndpoint, + ResolvedRobotResource, ResolvedSkillBinding, ResourceClaim, SkillPolicyPreset, + EffectAssurance, ProfileValidationError, UnsupportedSkillError, + AmbiguousSkillBindingError, SemanticEffectSpec, EffectMonitorRef, EffectMonitor, + EffectEvidenceCollector, SceneRegistry, RegistrySceneProvider, + SceneEntityRegistration, SceneEntityMetadata, SceneEntityStateProvider, + SceneGeometryProvider, SceneEntityRef, SceneObjectRef, SceneArticulationRef, + SceneLinkRef, SceneAffordanceRef, SceneDynamics, SceneCollisionRole, + SceneCollisionWorldMode, GRASP_AFFORDANCE_CAPABILITY, + PLACE_ON_AFFORDANCE_CAPABILITY, PLACE_IN_AFFORDANCE_CAPABILITY, + UnsupportedSceneAffordanceError, AmbiguousSceneAffordanceError, + ArticulationJointObservationCallback, BinaryObservationCallback, + COMPOSITE_EFFECT_MONITOR_ID, COMPOSITE_EFFECT_MONITOR_REVISION, + CONTACT_EFFECT_CHANNEL, CONSTRAINT_EFFECT_CHANNEL, + CONTROL_PART_EVIDENCE_PROVIDER_ID, CONTROL_PART_EVIDENCE_PROVIDER_REVISION, + DeclarativeValue, EffectClause, EffectEvidenceBatch, EffectEvidenceQueryValue, + EffectMonitorParam, EffectStateExpectation, FORCE_EFFECT_CHANNEL, + JOINT_STATE_EFFECT_CHANNEL, POSE_RELATION_EFFECT_CHANNEL, + PLACEMENT_TARGET_AFFORDANCE_REVISION, PathPart, PlaceRelationTarget, + SCENE_ARTICULATION_EVIDENCE_PROVIDER_ID, + SCENE_ARTICULATION_EVIDENCE_PROVIDER_REVISION, ScalarObservationCallback .. rubric:: Semantic calls and catalog @@ -269,3 +296,57 @@ Affordance capabilities and errors .. autoclass:: UnsupportedSceneAffordanceError .. autoclass:: AmbiguousSceneAffordanceError + +Evidence constants and type aliases +----------------------------------- + +.. currentmodule:: embodichain.lab.task_program.semantics + +These exported constants identify evidence channels and provider revisions; +the aliases describe accepted clauses, observations and callback signatures. + +.. autodata:: ArticulationJointObservationCallback + +.. autodata:: BinaryObservationCallback + +.. autodata:: COMPOSITE_EFFECT_MONITOR_ID + +.. autodata:: COMPOSITE_EFFECT_MONITOR_REVISION + +.. autodata:: CONTACT_EFFECT_CHANNEL + +.. autodata:: CONSTRAINT_EFFECT_CHANNEL + +.. autodata:: CONTROL_PART_EVIDENCE_PROVIDER_ID + +.. autodata:: CONTROL_PART_EVIDENCE_PROVIDER_REVISION + +.. autodata:: DeclarativeValue + +.. autodata:: EffectClause + +.. autodata:: EffectEvidenceBatch + +.. autodata:: EffectEvidenceQueryValue + +.. autodata:: EffectMonitorParam + +.. autodata:: EffectStateExpectation + +.. autodata:: FORCE_EFFECT_CHANNEL + +.. autodata:: JOINT_STATE_EFFECT_CHANNEL + +.. autodata:: POSE_RELATION_EFFECT_CHANNEL + +.. autodata:: PLACEMENT_TARGET_AFFORDANCE_REVISION + +.. autodata:: PathPart + +.. autodata:: PlaceRelationTarget + +.. autodata:: SCENE_ARTICULATION_EVIDENCE_PROVIDER_ID + +.. autodata:: SCENE_ARTICULATION_EVIDENCE_PROVIDER_REVISION + +.. autodata:: ScalarObservationCallback diff --git a/embodichain/agents/mllm/task_program.py b/embodichain/agents/mllm/task_program.py index cdbb24607..cbebe891a 100644 --- a/embodichain/agents/mllm/task_program.py +++ b/embodichain/agents/mllm/task_program.py @@ -172,8 +172,8 @@ def decode_mllm_task_program( Raises: TypeError: If ``integration`` is not an exact integration config. - TaskProgramDecodeError: If JSON, schema, or MLLM policy validation - fails. + embodichain.lab.task_program.TaskProgramDecodeError: If JSON, schema, + or MLLM policy validation fails. """ if type(integration) is not TaskProgramIntegrationCfg: raise TypeError("integration must be exactly TaskProgramIntegrationCfg.") @@ -224,8 +224,8 @@ def compile_mllm_task_program( Raises: TypeError: If ``adapter`` or ``integration`` has the wrong exact type. - TaskProgramDecodeError: If JSON, schema, or MLLM policy validation - fails. + embodichain.lab.task_program.TaskProgramDecodeError: If JSON, schema, + or MLLM policy validation fails. """ if type(adapter) is not TaskProgramEnvironmentAdapter: raise TypeError("adapter must be exactly TaskProgramEnvironmentAdapter.")