Asset generalization

Asset generalization#

Asset generalization preserves logical task roles while selecting compatible rigid assets. Source protocols live in data; task requirements remain in Task Program semantics. Online generation adapters are deferred.

embodichain.data.asset_catalog#

Provider-neutral asset records and the candidate/materialization protocol.

`AssetCandidate`	Candidate identity and provider locator, with optional provisional metadata.
`AssetDescriptor`	Identity, semantics and local geometry of one rigid asset revision.
`AssetProvider`	Acquire candidates and prepare local assets without task dependencies.
`AssetQuery`	Source-neutral semantic constraints used to request candidates.
`Bounds3D`	Axis-aligned local bounds; planar bounds are allowed for support regions.
`PreparationContext`	Local destination supplied to asset preparation.
`PreparedAsset`	Prepared local files and content identity, ready for task-level validation.

class embodichain.data.asset_catalog.AssetCandidate[source]#

Candidate identity and provider locator, with optional provisional metadata.

Parameters:

candidate_id (str) – Stable candidate identifier within its source.
source_uri (str) – Provider-owned locator or generation recipe identifier.
descriptor (AssetDescriptor | None) – Optional preliminary description, revalidated on preparation.

Methods:

`__init__`(candidate_id, source_uri[, descriptor])
`from_dict`(data)	Decode one candidate snapshot.

__init__(candidate_id, source_uri, descriptor=None)#

classmethod from_dict(data)[source]#

Decode one candidate snapshot.

Return type:: AssetCandidate

class embodichain.data.asset_catalog.AssetDescriptor[source]#

Identity, semantics and local geometry of one rigid asset revision.

Parameters:

asset_id (str) – Stable identity within the provider.
category (str | None) – Known semantic category; None means unknown.
attributes (Mapping[str, Any]) – Known scalar semantic properties.
capabilities (tuple[str, ...]) – Explicit declared capabilities.
bounds_m (Bounds3D | None) – Full object geometry bounds in normalized local coordinates.
support_region (Bounds3D | None) – Usable horizontal support rectangle; Z is constant.
container_region (Bounds3D | None) – Usable interior box, not the exterior bounding box.
provenance (Mapping[str, Any]) – JSON evidence/source records, optionally keyed by field.
normalized (bool) – Whether geometry is rigid, in meters and right-handed Z-up.

Methods:

`__init__`(asset_id[, category, attributes, ...])
`from_dict`(data)	Decode metadata, rejecting unknown keys and invalid nested bounds.

__init__(asset_id, category=None, attributes=<factory>, capabilities=(), bounds_m=None, support_region=None, container_region=None, provenance=<factory>, normalized=False)#

classmethod from_dict(data)[source]#

Decode metadata, rejecting unknown keys and invalid nested bounds.

Return type:: AssetDescriptor

class embodichain.data.asset_catalog.AssetProvider[source]#

Acquire candidates and prepare local assets without task dependencies.

Methods:

`__init__`(args, *kwargs)
`candidates`(request, *, limit)	Return at most `limit` provisional candidates for the query.
`materialize`(candidate, *, context)	Prepare one candidate and independently validate its resulting metadata.

__init__(*args, **kwargs)#

candidates(request, *, limit)[source]#

Return at most limit provisional candidates for the query.

Parameters:

request (AssetQuery) – Semantic selection constraints.
limit (int) – Positive maximum candidate count.

Return type:

Sequence[AssetCandidate]

Returns:

Candidate snapshots requiring preparation and authoritative matching.

materialize(candidate, *, context)[source]#

Prepare one candidate and independently validate its resulting metadata.

Parameters:

candidate (AssetCandidate) – Candidate owned by this provider.
context (PreparationContext) – Local preparation destination.

Return type:

PreparedAsset

Returns:

Normalized local assets with dependency-complete content identity.

class embodichain.data.asset_catalog.AssetQuery[source]#

Source-neutral semantic constraints used to request candidates.

Parameters:

category (str | None) – Exact semantic category, or no category restriction.
attributes (Mapping[str, Any]) – Required JSON scalar properties.
capabilities (tuple[str, ...]) – Explicit required capabilities, independent of category.

Methods:

`__init__`([category, attributes, capabilities])
`from_dict`(data)	Decode a closed semantic query mapping.

__init__(category=None, attributes=<factory>, capabilities=())#

classmethod from_dict(data)[source]#

Decode a closed semantic query mapping.

Return type:: AssetQuery

class embodichain.data.asset_catalog.Bounds3D[source]#

Axis-aligned local bounds; planar bounds are allowed for support regions.

Parameters:

lower (tuple[float, float, float]) – Three minimum coordinates, in meters.
upper (tuple[float, float, float]) – Three maximum coordinates, in meters.

Methods:

`__init__`(lower, upper)
`from_dict`(data)	Decode a closed bounds mapping.

Attributes:

extents

Return the axis-aligned X, Y and Z lengths in meters.

__init__(lower, upper)#

property extents: tuple[float, float, float]#: Return the axis-aligned X, Y and Z lengths in meters.

classmethod from_dict(data)[source]#

Decode a closed bounds mapping.

Return type:: Bounds3D

class embodichain.data.asset_catalog.PreparationContext[source]#

Local destination supplied to asset preparation.

Parameters:: cache_dir (str) – Absolute path to the content-addressed preparation cache.

Methods:

`__init__`(cache_dir)
`from_dict`(data)	Decode a preparation context.

__init__(cache_dir)#

classmethod from_dict(data)[source]#

Decode a preparation context.

Return type:: PreparationContext

class embodichain.data.asset_catalog.PreparedAsset[source]#

Prepared local files and content identity, ready for task-level validation.

Parameters:

descriptor (AssetDescriptor) – Normalized asset description.
visual_path (str) – Absolute local visual model path.
collision_path (str) – Absolute local collision model path.
content_sha256 (str) – SHA-256 over descriptor and all model dependencies.
provenance (Mapping[str, Any]) – Preparation/source evidence. package_root names an absolute prepared directory; files maps all package-relative filenames to SHA-256 digests. Neither is a task acceptance result.

Providers return the common package snapshot consumed by embodichain.data.asset_catalog.verify_prepared_asset(): an asset.catalog.json plus all local geometry dependencies. Content identity hashes the canonical JSON descriptor and sorted package file-digest mapping. File existence and dependency hashing belong to the preparing provider. The record validates format and snapshots metadata without doing I/O.

Methods:

`__init__`(descriptor, visual_path, ...[, ...])
`from_dict`(data)	Decode a prepared asset snapshot without loading its files.

__init__(descriptor, visual_path, collision_path, content_sha256, provenance=<factory>)#

classmethod from_dict(data)[source]#

Decode a prepared asset snapshot without loading its files.

Return type:: PreparedAsset

embodichain.data.asset_catalog.contracts#

Immutable JSON-compatible records. Geometry is explicitly normalized to metres and Z-up; prepared identity covers resources and annotations.

`Bounds3D`	Axis-aligned local bounds; planar bounds are allowed for support regions.
`AssetDescriptor`	Identity, semantics and local geometry of one rigid asset revision.
`AssetCandidate`	Candidate identity and provider locator, with optional provisional metadata.
`PreparedAsset`	Prepared local files and content identity, ready for task-level validation.
`AssetQuery`	Source-neutral semantic constraints used to request candidates.
`PreparationContext`	Local destination supplied to asset preparation.
`AssetProvider`	Acquire candidates and prepare local assets without task dependencies.

class embodichain.data.asset_catalog.contracts.Bounds3D[source]#

Axis-aligned local bounds; planar bounds are allowed for support regions.

Parameters:

lower (tuple[float, float, float]) – Three minimum coordinates, in meters.
upper (tuple[float, float, float]) – Three maximum coordinates, in meters.

Methods:

`__init__`(lower, upper)
`from_dict`(data)	Decode a closed bounds mapping.

Attributes:

extents

Return the axis-aligned X, Y and Z lengths in meters.

__init__(lower, upper)#

property extents: tuple[float, float, float]#: Return the axis-aligned X, Y and Z lengths in meters.

classmethod from_dict(data)[source]#

Decode a closed bounds mapping.

Return type:: Bounds3D

class embodichain.data.asset_catalog.contracts.AssetDescriptor[source]#

Identity, semantics and local geometry of one rigid asset revision.

Parameters:

asset_id (str) – Stable identity within the provider.
category (str | None) – Known semantic category; None means unknown.
attributes (Mapping[str, Any]) – Known scalar semantic properties.
capabilities (tuple[str, ...]) – Explicit declared capabilities.
bounds_m (Bounds3D | None) – Full object geometry bounds in normalized local coordinates.
support_region (Bounds3D | None) – Usable horizontal support rectangle; Z is constant.
container_region (Bounds3D | None) – Usable interior box, not the exterior bounding box.
provenance (Mapping[str, Any]) – JSON evidence/source records, optionally keyed by field.
normalized (bool) – Whether geometry is rigid, in meters and right-handed Z-up.

Methods:

`__init__`(asset_id[, category, attributes, ...])
`from_dict`(data)	Decode metadata, rejecting unknown keys and invalid nested bounds.

__init__(asset_id, category=None, attributes=<factory>, capabilities=(), bounds_m=None, support_region=None, container_region=None, provenance=<factory>, normalized=False)#

classmethod from_dict(data)[source]#

Decode metadata, rejecting unknown keys and invalid nested bounds.

Return type:: AssetDescriptor

class embodichain.data.asset_catalog.contracts.AssetCandidate[source]#

Candidate identity and provider locator, with optional provisional metadata.

Parameters:

candidate_id (str) – Stable candidate identifier within its source.
source_uri (str) – Provider-owned locator or generation recipe identifier.
descriptor (AssetDescriptor | None) – Optional preliminary description, revalidated on preparation.

Methods:

`__init__`(candidate_id, source_uri[, descriptor])
`from_dict`(data)	Decode one candidate snapshot.

__init__(candidate_id, source_uri, descriptor=None)#

classmethod from_dict(data)[source]#

Decode one candidate snapshot.

Return type:: AssetCandidate

class embodichain.data.asset_catalog.contracts.PreparedAsset[source]#

Prepared local files and content identity, ready for task-level validation.

Parameters:

descriptor (AssetDescriptor) – Normalized asset description.
visual_path (str) – Absolute local visual model path.
collision_path (str) – Absolute local collision model path.
content_sha256 (str) – SHA-256 over descriptor and all model dependencies.
provenance (Mapping[str, Any]) – Preparation/source evidence. package_root names an absolute prepared directory; files maps all package-relative filenames to SHA-256 digests. Neither is a task acceptance result.

Providers return the common package snapshot consumed by embodichain.data.asset_catalog.verify_prepared_asset(): an asset.catalog.json plus all local geometry dependencies. Content identity hashes the canonical JSON descriptor and sorted package file-digest mapping. File existence and dependency hashing belong to the preparing provider. The record validates format and snapshots metadata without doing I/O.

Methods:

`__init__`(descriptor, visual_path, ...[, ...])
`from_dict`(data)	Decode a prepared asset snapshot without loading its files.

__init__(descriptor, visual_path, collision_path, content_sha256, provenance=<factory>)#

classmethod from_dict(data)[source]#

Decode a prepared asset snapshot without loading its files.

Return type:: PreparedAsset

class embodichain.data.asset_catalog.contracts.AssetQuery[source]#

Source-neutral semantic constraints used to request candidates.

Parameters:

category (str | None) – Exact semantic category, or no category restriction.
attributes (Mapping[str, Any]) – Required JSON scalar properties.
capabilities (tuple[str, ...]) – Explicit required capabilities, independent of category.

Methods:

`__init__`([category, attributes, capabilities])
`from_dict`(data)	Decode a closed semantic query mapping.

__init__(category=None, attributes=<factory>, capabilities=())#

classmethod from_dict(data)[source]#

Decode a closed semantic query mapping.

Return type:: AssetQuery

class embodichain.data.asset_catalog.contracts.PreparationContext[source]#

Local destination supplied to asset preparation.

Parameters:: cache_dir (str) – Absolute path to the content-addressed preparation cache.

Methods:

`__init__`(cache_dir)
`from_dict`(data)	Decode a preparation context.

__init__(cache_dir)#

classmethod from_dict(data)[source]#

Decode a preparation context.

Return type:: PreparationContext

class embodichain.data.asset_catalog.contracts.AssetProvider[source]#

Acquire candidates and prepare local assets without task dependencies.

Methods:

`__init__`(args, *kwargs)
`candidates`(request, *, limit)	Return at most `limit` provisional candidates for the query.
`materialize`(candidate, *, context)	Prepare one candidate and independently validate its resulting metadata.

__init__(*args, **kwargs)#

candidates(request, *, limit)[source]#

Return at most limit provisional candidates for the query.

Parameters:

request (AssetQuery) – Semantic selection constraints.
limit (int) – Positive maximum candidate count.

Return type:

Sequence[AssetCandidate]

Returns:

Candidate snapshots requiring preparation and authoritative matching.

materialize(candidate, *, context)[source]#

Prepare one candidate and independently validate its resulting metadata.

Parameters:

candidate (AssetCandidate) – Candidate owned by this provider.
context (PreparationContext) – Local preparation destination.

Return type:

PreparedAsset

Returns:

Normalized local assets with dependency-complete content identity.

embodichain.lab.task_program.semantics.asset_requirements#

Task-owned role requirements and explicit category aliases. Geometric relations require declared usable regions and preserve task semantics.

`AssetRoleRequirement`	Requirements for a stable Task Program entity.
`AssetRelationRequirement`	Geometric relation between two selected asset roles.
`AssetRequirements`	Immutable task role contract used by matching and scene materialization.

class embodichain.lab.task_program.semantics.asset_requirements.AssetRoleRequirement[source]#

Requirements for a stable Task Program entity.

Parameters:

entity_id (str) – Stable program object identifier retained across asset changes.
query (AssetQuery) – Required semantic category, properties and capabilities.
max_extent_m (float | None) – Optional upper bound on every object dimension.

Methods:

`__init__`(entity_id, query[, max_extent_m])
`from_dict`(data)	Decode a role declaration, rejecting unknown keys.
`to_dict`()	Return a detached JSON-compatible role declaration.

__init__(entity_id, query, max_extent_m=None)#

classmethod from_dict(data)[source]#

Decode a role declaration, rejecting unknown keys.

Return type:: AssetRoleRequirement

to_dict()[source]#

Return a detached JSON-compatible role declaration.

Return type:: dict[str, Any]

class embodichain.lab.task_program.semantics.asset_requirements.AssetRelationRequirement[source]#

Geometric relation between two selected asset roles.

Parameters:

kind (Literal['fits_inside', 'supported_by', 'pours_into']) – Containment, support, or annotated pouring-aperture compatibility. pours_into compares source-mouth and target-opening radii; it does not require the bottle body to fit inside the cup.
object_role (str) – Role of the manipulated object.
target_role (str) – Role of its container or support.
clearance_m (float) – Required nonnegative inset on each relevant side; for pours_into, add it to the source radius before comparing with the target opening radius.

Methods:

`__init__`(kind, object_role, target_role[, ...])
`from_dict`(data)	Decode a closed relation declaration.
`to_dict`()	Return a JSON-compatible relation declaration.

__init__(kind, object_role, target_role, clearance_m=0.0)#

classmethod from_dict(data)[source]#

Decode a closed relation declaration.

Return type:: AssetRelationRequirement

to_dict()[source]#

Return a JSON-compatible relation declaration.

Return type:: dict[str, Any]

class embodichain.lab.task_program.semantics.asset_requirements.AssetRequirements[source]#

Immutable task role contract used by matching and scene materialization.

Parameters:

roles (Mapping[str, AssetRoleRequirement]) – Named roles, each identifying a distinct program object.
relations (tuple[AssetRelationRequirement, ...]) – Required geometric relationships between named roles.
category_aliases (Mapping[str, str]) – Explicit alias-to-category edges; cycles are invalid.

Methods:

`__init__`(roles[, relations, category_aliases])
`from_dict`(data)	Decode requirements with strict nested role and relation validation.
`to_dict`()	Return a detached JSON-compatible requirements snapshot.

__init__(roles, relations=(), category_aliases=<factory>)#

classmethod from_dict(data)[source]#

Decode requirements with strict nested role and relation validation.

Return type:: AssetRequirements

to_dict()[source]#

Return a detached JSON-compatible requirements snapshot.

Return type:: dict[str, Any]

embodichain.data.asset_catalog additions#

Public source adapters and content verification for normalized local asset snapshots.

`verify_prepared_asset`(asset)	Verify the common prepared package contract before copy or execution.
`DirectoryAssetProvider`	Discover annotated packages recursively under one local directory.
`ExplicitAssetProvider`	Read a fixed collection of local asset packages.

embodichain.data.asset_catalog.verify_prepared_asset(asset)[source]#

Verify the common prepared package contract before copy or execution.

Any provider can produce this format: provenance.package_root names an absolute package directory and provenance.files maps every relative file to its SHA-256. The package contains asset.catalog.json. Content identity is SHA-256 of UTF-8 JSON {"descriptor": descriptor.to_dict(), "files": files}, with sorted keys, compact separators and no nonfinite values. Provider provenance outside the descriptor is deliberately excluded from identity.

Parameters:: asset (PreparedAsset) – Prepared snapshot from any provider using the common package format.
Raises:: ValueError – Provenance is absent or package metadata/files have changed.
Return type:: None

class embodichain.data.asset_catalog.DirectoryAssetProvider[source]#

Discover annotated packages recursively under one local directory.

Parameters:: directory (str | Path) – Root containing one or more asset.catalog.json packages.

Methods:

__init__(directory)

__init__(directory)[source]#

class embodichain.data.asset_catalog.ExplicitAssetProvider[source]#

Read a fixed collection of local asset packages.

Parameters:: paths (Sequence[str | Path]) – Catalog manifests, package directories, or model files with an adjacent asset.catalog.json naming that model.

Raw models without annotated catalogs are rejected with a preparation diagnostic. This provider does not invoke online generation or SimReady.

Methods:

`__init__`(paths)
`candidates`(request, *, limit)	Rank known semantic matches without excluding task-level aliases.
`materialize`(candidate, *, context)	Verify and cache a complete package, detecting missing or changed bytes.

__init__(paths)[source]#

candidates(request, *, limit)[source]#

Rank known semantic matches without excluding task-level aliases.

Parameters:

request (AssetQuery) – Source-neutral category, property and capability constraints.
limit (int) – Positive maximum number of candidates.

Return type:

tuple[AssetCandidate, ...]

Returns:

Stable candidate snapshots ordered by known matches and locator.

materialize(candidate, *, context)[source]#

Verify and cache a complete package, detecting missing or changed bytes.

Parameters:

candidate (AssetCandidate) – Candidate returned by this provider.
context (PreparationContext) – Cache destination outside the source package.

Return type:

PreparedAsset

Returns:

Validated local geometry with immutable descriptor and file provenance.

embodichain.data.asset_catalog.local additions#

Directory and explicit providers retain candidate metadata without claiming task compatibility. Materialization verifies real mesh bounds, local resource dependencies and the content-addressed snapshot. Other providers can emit the same verifiable package inventory.

`DirectoryAssetProvider`	Discover annotated packages recursively under one local directory.
`ExplicitAssetProvider`	Read a fixed collection of local asset packages.
`verify_prepared_asset`(asset)	Verify the common prepared package contract before copy or execution.

class embodichain.data.asset_catalog.local.DirectoryAssetProvider[source]#

Discover annotated packages recursively under one local directory.

Parameters:: directory (str | Path) – Root containing one or more asset.catalog.json packages.

Methods:

__init__(directory)

__init__(directory)[source]#

class embodichain.data.asset_catalog.local.ExplicitAssetProvider[source]#

Read a fixed collection of local asset packages.

Parameters:: paths (Sequence[str | Path]) – Catalog manifests, package directories, or model files with an adjacent asset.catalog.json naming that model.

Raw models without annotated catalogs are rejected with a preparation diagnostic. This provider does not invoke online generation or SimReady.

Methods:

`__init__`(paths)
`candidates`(request, *, limit)	Rank known semantic matches without excluding task-level aliases.
`materialize`(candidate, *, context)	Verify and cache a complete package, detecting missing or changed bytes.

__init__(paths)[source]#

candidates(request, *, limit)[source]#

Rank known semantic matches without excluding task-level aliases.

Parameters:

request (AssetQuery) – Source-neutral category, property and capability constraints.
limit (int) – Positive maximum number of candidates.

Return type:

tuple[AssetCandidate, ...]

Returns:

Stable candidate snapshots ordered by known matches and locator.

materialize(candidate, *, context)[source]#

Verify and cache a complete package, detecting missing or changed bytes.

Parameters:

candidate (AssetCandidate) – Candidate returned by this provider.
context (PreparationContext) – Cache destination outside the source package.

Return type:

PreparedAsset

Returns:

Validated local geometry with immutable descriptor and file provenance.

embodichain.data.asset_catalog.local.verify_prepared_asset(asset)[source]#

Verify the common prepared package contract before copy or execution.

Any provider can produce this format: provenance.package_root names an absolute package directory and provenance.files maps every relative file to its SHA-256. The package contains asset.catalog.json. Content identity is SHA-256 of UTF-8 JSON {"descriptor": descriptor.to_dict(), "files": files}, with sorted keys, compact separators and no nonfinite values. Provider provenance outside the descriptor is deliberately excluded from identity.

Parameters:: asset (PreparedAsset) – Prepared snapshot from any provider using the common package format.
Raises:: ValueError – Provenance is absent or package metadata/files have changed.
Return type:: None

embodichain.lab.task_program.semantics.asset_matching additions#

Bounded deterministic selection applies hard role constraints and upright geometric relations before freezing an asset set. Unknown metadata cannot satisfy required constraints; a resolved set does not certify physical success.

`AssetRejection`	One candidate or relationship rejection with its affected role.
`AssetResolutionError`	No assignment was found within the configured candidate/search bounds.
`ResolvedAssetSet`	Immutable role assignment with content and requirement identity.
`resolve_asset_set`(requirements, ...[, seed, ...])	Select the first valid seeded assignment using bounded iterative search.

class embodichain.lab.task_program.semantics.asset_matching.AssetRejection[source]#

One candidate or relationship rejection with its affected role.

Methods:

__init__(role, asset_id, code, detail[, ...])

__init__(role, asset_id, code, detail, target_role=None)#

class embodichain.lab.task_program.semantics.asset_matching.AssetResolutionError[source]#

No assignment was found within the configured candidate/search bounds.

Methods:

__init__(message, *, rejections[, ...])

__init__(message, *, rejections, search_nodes=0, budget_exhausted=False)[source]#

class embodichain.lab.task_program.semantics.asset_matching.ResolvedAssetSet[source]#

Immutable role assignment with content and requirement identity.

Absolute local paths are retained for loading but excluded from set_id; copying the same prepared content into another cache keeps its identity.

Methods:

`__init__`(assets, seed, requirements_sha256)
`to_dict`()	Return an independent JSON-compatible manifest for batch provenance.

__init__(assets, seed, requirements_sha256)#

to_dict()[source]#

Return an independent JSON-compatible manifest for batch provenance.

Return type:: dict[str, Any]

embodichain.lab.task_program.semantics.asset_matching.resolve_asset_set(requirements, candidates_by_role, *, seed=0, max_candidates_per_role=100, max_search_nodes=1000)[source]#

Select the first valid seeded assignment using bounded iterative search.

Candidate identities are sorted before seeded ranking, so provider iteration order cannot affect selection. At most max_candidates_per_role unique candidates per role are evaluated. This is a search budget, not a guarantee that a satisfying assignment will be found. Pair constraints are checked as soon as both roles are assigned; the Cartesian product is never allocated.

Parameters:

requirements (AssetRequirements) – Validated task-role constraints and explicit aliases.
candidates_by_role (Mapping[str, Sequence[PreparedAsset]]) – Prepared candidates for exactly the required roles.
seed (int) – Integer defining deterministic candidate ranking.
max_candidates_per_role (int) – Candidate evaluation limit for each role.
max_search_nodes (int) – Maximum attempted partial-assignment extensions.

Raises:

ValueError – If input role sets or budgets are invalid.
AssetResolutionError – If no assignment passes within the budgets.

Return type:

ResolvedAssetSet

embodichain.lab.task_program.integrations.asset_materialization additions#

Materialize standalone configurations and semantic bindings without modifying templates. Recompute supported placement frames and reject unsupported fixed calibrations. Validate packaged content before loading.

`AssetAdaptationCfg`	Explicit geometry adaptation for source templates without primitive bounds.
`MaterializedAssetDeployment`	A preflighted deployment and its immutable asset manifest.
`load_asset_requirements_from_deployment`(...)	Read the strict optional role contract from the selected integration.
`materialize_asset_deployment`(...[, adaptations])	Build and preflight a new deployment without modifying its source files.
`validate_materialized_deployment`(deployment)	Verify file digests and asset identity before environment construction.

class embodichain.lab.task_program.integrations.asset_materialization.AssetAdaptationCfg[source]#

Explicit geometry adaptation for source templates without primitive bounds.

Methods:

`__init__`([pour, initial_bottom_z_m])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

Attributes:

`initial_bottom_z_m`	World height of each role's initial bottom; upright poses only.
`pour`	Explicit selected-asset calibration for the four-segment PourWater task.

__init__(pour=<factory>, initial_bottom_z_m=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

initial_bottom_z_m: dict[str, float]#: World height of each role’s initial bottom; upright poses only.

pour: AssetPourAdaptationCfg | None#: Explicit selected-asset calibration for the four-segment PourWater task.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.task_program.integrations.asset_materialization.MaterializedAssetDeployment[source]#

A preflighted deployment and its immutable asset manifest.

Methods:

__init__(deployment_path, asset_set_id, ...)

__init__(deployment_path, asset_set_id, manifest_path, manifest_sha256='')#

embodichain.lab.task_program.integrations.asset_materialization.load_asset_requirements_from_deployment(task_config_path)[source]#

Read the strict optional role contract from the selected integration.

Return type:: AssetRequirements

embodichain.lab.task_program.integrations.asset_materialization.materialize_asset_deployment(task_config_path, requirements, resolved_assets, *, output_dir, adaptations=None)[source]#

Build and preflight a new deployment without modifying its source files.

Place calls must use a semantic support/container covered by a role relation. Calibrated grasps, rotated initial poses and absolute Place targets fail closed. Prepared assets must contain the verifiable package inventory contract. Resources are bundled locally; packaged robot/data identifiers retain normal SDK resolution. Output directories must be absent or empty.

Return type:: MaterializedAssetDeployment

embodichain.lab.task_program.integrations.asset_materialization.validate_materialized_deployment(deployment)[source]#

Verify file digests and asset identity before environment construction.

Return type:: None

embodichain.lab.gym.envs.asset_generalization additions#

Prepare bounded asset batches, build fresh single-environment task runtimes, execute through the canonical scene acceptance path, and preserve reset/close recording boundaries. Initial and measured validation callbacks are required; submitted resets are not persistence receipts.

`AssetGeneralizationCfg`	Finite preparation and execution budgets for rigid asset batches.
`AssetEpisodeOutcome`	Execution acceptance and reset submission for one episode.
`AssetBatchOutcome`	Batch outcomes; close_finalized refers to the shared session's final close.
`prepare_asset_batches`(task_config_path, ...)	Prepare a bounded candidate snapshot and materialize seeded task batches.
`collect_asset_batches`(deployments, *, cfg, ...)	Collect sequential B=1 batches using canonical fail-closed scene execution.

class embodichain.lab.gym.envs.asset_generalization.AssetGeneralizationCfg[source]#

Finite preparation and execution budgets for rigid asset batches.

Parameters:

seed (int) – Base uint32 seed; batch i uses seed + i.
max_batches (int) – Maximum prepared or collected asset combinations.
episodes_per_batch (int) – Number of attempts on each fixed asset combination.
candidates_per_role (int) – Maximum candidates acquired once for each role.
max_search_nodes (int) – Matcher budget for partial assignment extensions.
settle_steps (int) – Physics substeps before initial scene validation.
record_trajectory (bool) – Explicitly enable accepted-episode trajectory saving during collection with the default factory; preparation never records.

Count limits are at most one million; zero is allowed only for seed and settle_steps. Mutated configurations are revalidated at operation entry.

Methods:

`__init__`([seed, max_batches, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

__init__(seed=<factory>, max_batches=<factory>, episodes_per_batch=<factory>, candidates_per_role=<factory>, max_search_nodes=<factory>, settle_steps=<factory>, record_trajectory=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.gym.envs.asset_generalization.AssetEpisodeOutcome[source]#

Execution acceptance and reset submission for one episode.

reset_submitted means the reset returned after the commit/discard request; it is not a durable persistence receipt. accepted is physical/program acceptance, independent of whether recording is configured.

Methods:

__init__(episode_index, accepted, ...)

__init__(episode_index, accepted, reset_submitted)#

class embodichain.lab.gym.envs.asset_generalization.AssetBatchOutcome[source]#

Batch outcomes; close_finalized refers to the shared session’s final close.

Methods:

__init__(batch_index, asset_set_id, ...)

__init__(batch_index, asset_set_id, episodes, close_finalized)#

embodichain.lab.gym.envs.asset_generalization.prepare_asset_batches(task_config_path, providers_by_role, *, cfg, output_dir, adaptations=None)[source]#

Prepare a bounded candidate snapshot and materialize seeded task batches.

Provider failures reject their candidate and remain in preparation.report.json. If a role has no eligible assets, matching fails with its ordinary structured diagnostics. Candidate acquisition is performed once per role; every batch selects from the same prepared snapshot. No online provider is implicitly enabled or substituted.

Parameters:

task_config_path (str | Path) – Deployment whose integration declares asset roles.
providers_by_role (Mapping[str, AssetProvider]) – Exactly one explicitly supplied provider per role.
cfg (AssetGeneralizationCfg) – Candidate, batch and deterministic selection budgets.
output_dir (str | Path) – Absent or empty directory for cache and batch deployments.
adaptations (AssetAdaptationCfg | None) – Explicit scene geometry adaptation passed to materialization.

Return type:

tuple[MaterializedAssetDeployment, ...]

Returns:

Fresh offline deployment artifacts, in batch order.

embodichain.lab.gym.envs.asset_generalization.collect_asset_batches(deployments, *, cfg, initial_validator, measured_validator, environment_factory=None, report_path=None)[source]#

Collect sequential B=1 batches using canonical fail-closed scene execution.

One environment and its recorders are retained across batches. Only selected bodies are replaced; every batch obtains fresh task bindings and a new scene acceptance snapshot. Cleanup is drained after the final close and successful helper-frame unwind; a failed native constructor or execution traceback must be released by its caller before deferred cleanup can safely be drained. Exceptions preserve their original identity when close or reporting also fails.

Parameters:

deployments (Sequence[MaterializedAssetDeployment]) – Offline materialized artifacts, bounded by max_batches.
cfg (AssetGeneralizationCfg) – Execution count, seed and settling budgets.
initial_validator (Callable[[EmbodiedEnv], ValidationResult]) – Required measured checks of the prepared scene.
measured_validator (Callable[[EmbodiedEnv], ValidationResult]) – Required independent final task checks.
environment_factory (Callable[..., EmbodiedEnv] | None) – Optional factory accepting (deployment, seed=…). Called once for the first deployment. Custom factories own recording configuration and directory isolation. The default creates one fresh recordings/run_* directory beside the first deployment; recorder counters and provenance distinguish the batches within that session.
report_path (str | Path | None) – Optional JSON lifecycle report, also written on failure.

Return type:

tuple[AssetBatchOutcome, ...]

Returns:

Acceptance, reset-submission and close-finalization outcomes. These are lifecycle observations, not per-episode persistence receipts.

Calibrated pouring and measured acceptance#

The explicit four-segment pouring adapter reads selected-asset mouth geometry, robot-profile-bound grasp calibration and tilt axes. It recomputes staging and return targets without relaxing unrelated calibration guards. The measured monitor requires simultaneous pose evidence and never certifies fluid transfer.

`embodichain.lab.task_program.integrations.asset_materialization.AssetPourAdaptationCfg`	Explicit role selection for calibrated bottle-to-cup pouring.
`embodichain.lab.task_program.integrations.simulation.asset_pouring.PouringAcceptanceMonitor`	Accumulate bounded pose evidence for one rigid bottle/cup episode.

class embodichain.lab.task_program.integrations.asset_materialization.AssetPourAdaptationCfg[source]#

Explicit role selection for calibrated bottle-to-cup pouring.

Geometry/calibration evidence is read from each selected descriptor’s provenance.pouring record. Bottle calibration is tied to the exact selected embodiment profile_id.

Methods:

`__init__`([bottle_role, cup_role, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

__init__(bottle_role=<factory>, cup_role=<factory>, support_uid=<factory>, staging_target_id=<factory>, release_clearance_m=<factory>, mouth_clearance_m=<factory>)#

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

class embodichain.lab.task_program.integrations.simulation.asset_pouring.PouringAcceptanceMonitor[source]#

Accumulate bounded pose evidence for one rigid bottle/cup episode.

Both assets use meter-scale local coordinates with +Z as their upright axis. Mouth alignment is computed in the cup frame: the transformed bottle mouth must project inside the cup opening and lie within its positive height band while the bottle is tilted, on the same sampled control steps.

Parameters:

bottle_mouth_xyz (Sequence[float]) – Bottle mouth center in the bottle’s local frame.
cup_mouth_xyz (Sequence[float]) – Cup opening center in the cup’s local frame.
bottle_mouth_radius_m (float) – Conservative radius enclosing the bottle opening.
cup_opening_radius_m (float) – Radius of the usable circular cup opening.
min_tilt_rad (float) – Minimum bottle tilt from world +Z during pouring.
max_cup_displacement_m (float) – Maximum cup-origin excursion from its initial pose.
return_position_tolerance_m (float) – Final bottle-origin distance from its initial pose.
upright_tolerance_rad (float) – Maximum final bottle tilt and any sampled cup tilt.
min_mouth_height_m (float) – Minimum positive bottle-mouth height above cup opening.
max_mouth_height_m (float) – Maximum bottle-mouth height above cup opening.
min_pour_samples (int) – Minimum simultaneous qualifying control-step samples.

Only constant-size aggregates are retained. Sampling frequency is owned by the host; sample counts do not establish a continuous-time hold duration.

Methods:

`__init__`(*, bottle_mouth_xyz, cup_mouth_xyz, ...)
`observe`(bottle_pose, cup_pose, *, ...)	Record one control-step sample, retaining excursions outside pouring.
`reset`(initial_bottle_pose, initial_cup_pose)	Start a fresh episode from owned, finite proper SE(3) poses.
`to_metadata`()	Return an independent JSON-compatible evidence and threshold snapshot.
`validate_final`(bottle_pose, cup_pose)	Check sampled pouring geometry, all cup excursions and final return.

__init__(*, bottle_mouth_xyz, cup_mouth_xyz, bottle_mouth_radius_m, cup_opening_radius_m, min_tilt_rad=0.8726646259971648, max_cup_displacement_m=0.005, return_position_tolerance_m=0.02, upright_tolerance_rad=0.17453292519943295, min_mouth_height_m=0.015, max_mouth_height_m=0.25, min_pour_samples=2)[source]#

observe(bottle_pose, cup_pose, *, in_pour_segment)[source]#

Record one control-step sample, retaining excursions outside pouring.

Invalid poses or a non-boolean segment marker poison this episode’s evidence and raise. Catching that error cannot later accept the episode.

Return type:: None

reset(initial_bottle_pose, initial_cup_pose)[source]#

Start a fresh episode from owned, finite proper SE(3) poses.

Any invalid reset clears prior evidence before raising ValueError.

Return type:: None

to_metadata()[source]#

Return an independent JSON-compatible evidence and threshold snapshot.

Return type:: dict[str, Any]

validate_final(bottle_pose, cup_pose)[source]#

Check sampled pouring geometry, all cup excursions and final return.

Missing reset or samples produce unavailable checks. Final poses cannot add qualifying pour samples. Invalid final poses raise and poison the episode, preventing a later valid pose from hiding the missing evidence.

Return type:: ValidationResult

Asset generalization

Contents

Asset generalization#

embodichain.data.asset_catalog#

embodichain.data.asset_catalog.contracts#

embodichain.lab.task_program.semantics.asset_requirements#

embodichain.data.asset_catalog additions#

embodichain.data.asset_catalog.local additions#

embodichain.lab.task_program.semantics.asset_matching additions#

embodichain.lab.task_program.integrations.asset_materialization additions#

embodichain.lab.gym.envs.asset_generalization additions#

Calibrated pouring and measured acceptance#