Asset-Conditioned Prior Module

Asset-Conditioned Prior Module (ACPM) is a standalone Python package that turns asset-specific HSSD annotations into deterministic placement constraints. It checks a concrete asset candidate before SceneExpert mutates the scene, then returns an allow/block decision, traceable evidence, and repair suggestions.

Standalone repository | SceneExpert integration branch | HSSD annotations

What ACPM solves

Category-level rules are not enough for many 3D assets. Two wardrobes can have different door sweeps, functional fronts, support requirements, or replacement geometry. ACPM resolves constraints for the selected HSSD realization and checks the candidate in its actual world transform.

ACPM is an asset-conditioned constraint checker. It is not a scene generator, a second planner, or a replacement for SceneSmith's physics and aesthetic checks. The standalone package does not import SceneExpert, SceneSmith, Drake, Blender, or Hydra.

selected HSSD asset + candidate transform + current scene obstacles
                              |
                              v
                    AssetConstraintBrief
                              |
                              v
                 deterministic candidate check
                              |
                              v
       allow commit | block commit | repair/replace suggestion
                              |
                              v
                    registry + bounded trace

Current status

• The standalone package is maintained on the main branch of the Hex671 repository.
• The SceneExpert acpm-module-sync branch contains the complete adapter, configuration, mutation hooks, acceptance tooling, and a vendored copy of this package. It is not only a source-folder import.
• Contract tests cover add, move, snap, rescale, composite commit, stage reconciliation, and registry rollback paths.
• A real-HSSD full-mode canary verifies the reject, repair, revalidate, and commit lifecycle. This is integration evidence, not a corpus-scale quality or false-positive benchmark.

The Python distribution version is 0.1.0. The SceneExpert bridge contract is sceneexpert-acpm@1.4, and the default policy contract is asset_prior_policy@1.4. These identifiers version different compatibility surfaces and therefore do not need to match.

Capabilities

• Resolve semantic identity, realization kind, support priors, functional-front evidence, and articulated clearance from HSSD records.
• Transform asset-local constraints into world space only when the geometry identity and transform evidence are valid.
• Evaluate both the candidate's own constraints and intrusion into clearance regions owned by existing assets.
• Keep candidate evaluation separate from commit, so rejected poses never enter the ACPM registry.
• Return structured violations, suggested translations, and replacement advice.
• Snapshot, restore, reconcile, and validate registry state at SceneExpert stage boundaries.
• Emit compact designer text, machine-readable scene-state fields, and bounded trace payloads through one bridge API.

Package layout

Asset-Conditioned Prior Module/
|-- src/asset_conditioned_prior/
|   |-- provider.py       # HSSD lookup and capability reporting
|   |-- resolver.py       # evidence-aware AssetConstraintBrief construction
|   |-- validator.py      # deterministic candidate checks
|   |-- runtime.py        # resolve/evaluate/commit lifecycle
|   |-- integration.py    # stable SceneExpertACPMBridge boundary
|   |-- registry.py       # room-local committed state and snapshots
|   `-- schemas.py        # versioned Pydantic DTOs
|-- config/asset_prior.yaml
|-- demo/                 # automatic browser visualization
|-- tests/                # unit, contract, and adversarial coverage
`-- pyproject.toml

Quick start

1. Install the package

ACPM requires Python 3.11.

git clone https://github.com/Hex671/Asset-Conditioned-Prior-Module.git
cd Asset-Conditioned-Prior-Module
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

On Windows PowerShell, create and activate the environment with:

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

2. Prepare HSSD annotations

HSSD annotations are an external dependency and are not bundled with ACPM. Obtain them according to the upstream repository's terms:

git clone https://github.com/K-Chronofox/hssd-annotations.git ../hssd-annotations
export HSSD_ANNOTATIONS_ROOT=/absolute/path/to/hssd-annotations

PowerShell equivalent:

$env:HSSD_ANNOTATIONS_ROOT = "C:\path\to\hssd-annotations"

The configured root may be the repository root or its data directory. ACPM expects hssd_annotation_lookup.json.gz and config.json below the resolved data directory.

3. Run a provider smoke test

acpm stats
acpm resolve 115400dd7dd9aa26ca595007f18b5a515626554d \
  --object-id wardrobe_0 \
  --stage furniture \
  --mode text_only

The first command reports provider capabilities and record coverage. The second resolves one known HSSD wardrobe record and prints the versioned brief as JSON.

4. Use the Python API

import os

from asset_conditioned_prior import (
    AssetPriorConfig,
    AssetPriorMode,
    AssetPriorRuntime,
    AssetResolveRequest,
)

# Minimal example: HSSD Y-up asset coordinates to a Z-up world at the origin.
world_from_asset = (
    (1.0, 0.0, 0.0, 0.0),
    (0.0, 0.0, -1.0, 0.0),
    (0.0, 1.0, 0.0, 0.0),
    (0.0, 0.0, 0.0, 1.0),
)

runtime = AssetPriorRuntime.from_hssd_root(
    os.environ["HSSD_ANNOTATIONS_ROOT"],
    config=AssetPriorConfig(mode=AssetPriorMode.TEXT_ONLY),
)

brief = runtime.resolve_asset(
    AssetResolveRequest(
        object_id="wardrobe_0",
        hssd_id="115400dd7dd9aa26ca595007f18b5a515626554d",
        stage="furniture",
        world_from_asset=world_from_asset,
        geometry_identity_valid=True,
        context={"include_affordance_info": True},
    )
)

print(brief.category)
print(brief.designer_summary)
print(brief.brief_digest)

The example transform exists only to make the coordinate convention explicit. Production code must supply the selected geometry's confirmed HSSD identity, its actual asset-to-world transform (including pose), and current scene obstacles. Resolving a brief by itself does not prove that a placement is safe.

Runtime modes

Mode	Resolve and trace	Designer text	Block hard violations
off	No	No	No
shadow	Yes	No	No
text_only	Yes	Yes	No
enforce	Yes	No	Yes
full	Yes	Yes	Yes

AssetPriorConfig() defaults to enabled shadow mode for safe standalone inspection. The SceneExpert adapter defaults to disabled off mode in its own configuration, so existing SceneSmith runs remain unchanged until ACPM is explicitly enabled.

SceneExpert integration

The integration is implemented as a thin adapter in scenesmith/scene_expert/acpm.py. SceneExpert supplies its scene types and transforms; ACPM returns plain Pydantic DTOs. The core lifecycle is:

1. after_asset_selected(...) resolves the concrete HSSD asset.
2. before_pose_commit(...) evaluates a candidate while the scene is unchanged.
3. SceneExpert performs the scene mutation only when the response allows it.
4. after_pose_commit(...) or after_pose_commits(...) commits ACPM registry state after the scene mutation succeeds.
5. Stage-end validation reconciles live scene objects and writes ACPM trace data.

The integration branch uses the vendored package by default. A typical explicit configuration is:

export SCENEEXPERT_ACPM_ENABLED=true
export SCENEEXPERT_ACPM_MODE=full
export SCENEEXPERT_ACPM_PACKAGE_PATH=/path/to/SceneExpert/external/asset_conditioned_prior
export SCENEEXPERT_ACPM_HSSD_ROOT=/path/to/hssd-annotations

Run the acceptance workflow from a configured SceneExpert checkout with an OpenAI-compatible Qwen endpoint and the normal SceneSmith runtime dependencies:

SCENEEXPERT_ACPM_ACCEPTANCE_MODE=full \
SCENEEXPERT_ACPM_HSSD_ROOT=/path/to/hssd-annotations \
bash scripts/run_acpm_acceptance.sh

python scripts/validate_acpm_run.py /path/to/trace_000000.json \
  --expected-mode full

The acceptance script defaults to full mode and one designer iteration. Set SCENEEXPERT_ACPM_ACCEPTANCE_DRY_RUN=1 to inspect the generated SceneExpert command without starting a scene run.

Interactive demo

The browser demo executes the real provider, runtime, and bridge against HSSD data, then visualizes one blocked wardrobe placement and its accepted repair:

python demo/server.py --hssd-root "$HSSD_ANNOTATIONS_ROOT"

Open http://127.0.0.1:8765. The room and assets are explanatory top-down drawings driven by live ACPM responses; they are not production mesh renders and do not claim a complete Qwen/Drake/Blender scene-generation run. See demo/README.md for the presentation sequence and deterministic recording frames.

Verification

Run the standalone checks from the module root:

python -m pytest -q
python -m ruff check src tests demo
python -m black --check src tests demo
python -m build

At this revision, the standalone test suite contains 91 passing tests. It covers provider loading, resolution, transforms, semantic identity, candidate evaluation, registry transactions, bridge contracts, adversarial inputs, and the automatic demo API.

Known limitations

• Current validation evidence is targeted integration coverage, not a corpus-level benchmark of constraint precision or scene-quality improvement.
• Semantic alias coverage is intentionally conservative and may require domain extensions for new asset taxonomies.
• Optional affordance records are sparse; missing optional evidence remains unavailable instead of being promoted to a hard rule.
• Non-articulated clearance is not enforced as hard geometry unless the source annotation provides a trusted frame.
• ACPM validates proposed candidates; it does not search the room for an optimal pose or replace SceneSmith's general task, aesthetic, and physics reasoning.

Documentation

• SceneExpert integration branch
• Design plan and contract notes
• Interactive demo guide

License status

This repository does not currently include an open-source license. Until the maintainer selects one, obtain permission before redistributing or using the code outside the project.