feat(agents): add strict expert program frontend

[yuecideng]

Description

Stack

• Layer: 7/14
• Base: feat/declarative-expert-program-runtime
• Depends on: feat(gym): add declarative expert program runtime #497
• Followed by: feat(tasks): add declarative task slices and rollout validation #500
  Add an MLLM-facing Expert Program frontend that renders the exact integration catalog into prompts and decodes model output through the same strict schema and preflight path used by files and Python callers.

The frontend cannot invent unregistered calls, providers, scene references, or low-level controller commands, preserving one semantic facade from generation through execution.

Refs #471
Refs #474

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

Not applicable.

Validation

• Focused coverage: pytest -q tests/agents/mllm/test_expert_program.py — 21 passed
• Final affected-suite regression on the stack tip: 1215 passed, 2 skipped, 8 deselected
• Changed Python files pass Black 26.3.1; the Sphinx build and rollout-report drift check pass at the stack tip

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding public/design documentation is included in this stack.
• Tests cover the affected behavior.
• No dependency update is required.

[greptile-apps]

Greptile Summary

The PR adds a strict MLLM-facing Expert Program decoder and compiler that inject host-owned integration settings, restrict model-authored program constructs, and delegate to the canonical environment compiler.

• Adds public MLLM decode and compile entry points.
• Rejects model-controlled integrations, disallowed calls, resource overrides, and explicit articulation motion values.
• Adds focused policy, compilation, and end-to-end frontend-equivalence coverage.
• Documents the new frontend in the API reference.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking issue identified.

The new frontend consistently applies strict parsing, canonical decoding, MLLM-specific policy checks, optional static validation, and the existing environment compilation path, while focused and end-to-end tests cover the principal reachable behaviors.

Important Files Changed

Filename	Overview
embodichain/agents/mllm/expert_program.py	Adds strict decoding and compilation wrappers with host integration injection and curated MLLM policy checks; no actionable defect was identified.
tests/agents/mllm/test_expert_program.py	Covers integration ownership, schema and call restrictions, resource policy, strict JSON handling, and canonical compilation behavior.
tests/gym/envs/expert_program/test_simulation_environment.py	Extends frontend-equivalence coverage through the production adapter and verified simulation execution path.
embodichain/agents/mllm/init.py	Exposes the two new MLLM Expert Program entry points.
docs/source/api_reference/embodichain/embodichain.lab.gym.envs.expert_program.rst	Adds API-reference entries and documents the frontend’s constrained version-one surface.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Model JSON response] --> B[Strict JSON parser]
    B --> C[Inject host-owned integration]
    C --> D[Canonical Expert Program decoder]
    D --> E[MLLM policy validation]
    E --> F{Validation context supplied?}
    F -->|Yes| G[Static reference validation]
    F -->|No| H[Canonical config]
    G --> H
    H --> I[Environment adapter compile]
    I --> J[Provider-free compiled program]

Loading

_{Reviews (1): Last reviewed commit: "feat(agents): add strict expert program ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds a strict MLLM-facing Expert Program frontend under embodichain.agents.mllm that (a) injects host-owned integration, (b) restricts the model to a curated schema-v1 surface, and (c) compiles via the existing Expert Program adapter/compiler path so model, config, and Python callers share one validation+lowering pipeline.

Changes:

• Introduces decode_mllm_expert_program() / compile_mllm_expert_program() with a narrow policy (schema v1 only, curated call types only, no resource overrides, host-injected integration).
• Adds focused unit tests for MLLM decode/compile behavior plus an integration-style equivalence test alongside existing simulation fixtures.
• Updates API reference docs to expose the new MLLM frontend functions.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/gym/envs/expert_program/test_simulation_environment.py	Extends simulation fixture tests to assert equivalence across Python calls, config decoding, and the MLLM frontend.
tests/agents/mllm/test_expert_program.py	New unit tests covering MLLM integration injection, strict policy rejection cases, strict JSON parsing behavior, and compile-time scene reference errors.
embodichain/agents/mllm/expert_program.py	Implements strict MLLM decode + compile frontend that reuses existing Expert Program parsing/decoding/validation and adapter compilation.
embodichain/agents/mllm/init.py	Exposes the MLLM frontend functions as the public embodichain.agents.mllm API surface.
embodichain/agents/init.py	Introduces the embodichain.agents package initializer for agent-facing frontends.
docs/source/api_reference/embodichain/embodichain.lab.gym.envs.expert_program.rst	Documents and publishes the MLLM frontend functions in the API reference.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.