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 frontend that injects host-owned integration configuration, decodes constrained Expert Program JSON, enforces sequential and curated-call policies, and delegates compilation through the existing environment adapter.

• Exposes decoding and compilation entry points through embodichain.agents.mllm.
• Rejects model-controlled integrations, unsupported program structures, registered calls, and resource overrides.
• Adds focused frontend tests and end-to-end equivalence coverage across MLLM, configuration, and Python skill paths.
• Updates API documentation and applies postponed annotation evaluation to affected compatibility modules.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
embodichain/agents/mllm/expert_program.py	Adds strict decoding, policy enforcement, trusted integration injection, and compilation delegation without an eligible follow-up defect.
tests/agents/mllm/test_expert_program.py	Covers integration ownership, schema and node restrictions, resource overrides, strict JSON failures, and adapter compilation.
tests/gym/envs/expert_program/test_simulation_environment.py	Extends runtime-equivalence coverage to confirm that MLLM, decoded configuration, and Python skill frontends produce equivalent invocations and results.
embodichain/agents/mllm/init.py	Exports the two new MLLM Expert Program entry points.
docs/source/api_reference/embodichain/embodichain.lab.gym.envs.expert_program.rst	Documents the constrained sequential MLLM frontend and its public functions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
M[MLLM JSON response] --> P[Strict JSON parser]
H[Host integration] --> I[Inject trusted integration]
P --> I
I --> D[Canonical Expert Program decoder]
D --> V[MLLM policy validation]
V --> A[Environment adapter compile]
A --> C[Provider-free compiled program]

Loading

_{Reviews (5): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | 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.