AGENTS.md@src/gnn/execute/pymdp git:20260906.e62b9e9A

Immutable. This exact content is served forever at /api/v1/blob/41e87d2e0bb4e17a.

# PyMDP Execute Submodule Agent Guide

## Purpose

Execute PyMDP scripts and simulation runs produced by render outputs, while
producing structured execution artifacts for downstream analysis.

## Canonical Public Surface

Use `src/gnn/execute/pymdp/__init__.py` as the source of truth. Exported symbols
include:

- Classes:
  - `PyMDPSimulation`
  - `create_demo_pymdp_simulation`
- Execution:
  - `run_pymdp_simulation(...)`
  - `execute_pymdp_simulation_from_gnn(...)`
  - `execute_pymdp_simulation(...)`
- Validation:
  - `validate_pymdp_environment(...)`
  - `get_pymdp_health_status(...)`
- Package detection:
  - `detect_pymdp_installation(...)`
  - `is_correct_pymdp_package(...)`
  - `get_pymdp_installation_instructions(...)`
  - `attempt_pymdp_auto_install(...)`
  - `validate_pymdp_for_execution(...)`
- Context:
  - `create_enhanced_pymdp_context(...)`
- Utility exports listed in `__all__`

Do not document non-exported helper names as public contract.

## Execution Boundary

- Execute step owns simulation/runtime artifacts.
- Analysis step owns charting and visualization output.
- Any mention of "real-time execute visualization" is out of scope for this
  folder.

## Dependency Boundary

- Required package: `inferactively-pymdp>=1.0.0` (JAX-first rewrite).
- Import style in code/examples:
  ```python
  import jax.numpy as jnp
  import jax.random as jr
  from pymdp.agent import Agent
  from pymdp import utils as pymdp_utils
  ```
- If pymdp 1.0.0+ is not importable, the execution path reports an explicit
  failed status via `simulation._require_pymdp_1`.
- Rollout loop uses the canonical 1.0.0 pattern:
  `infer_states(empirical_prior=…, return_info=True)` →
  `infer_policies(qs)` → `sample_action(q_pi, rng_key=…)` →
  `update_empirical_prior(action, qs)`.

## Key Internal Files

- `executor.py`
- `pymdp_simulation.py`
- `simulation.py`
- `pymdp_runner.py`
- `validator.py`
- `package_detector.py`
- `context.py`

## Documentation Maintenance Rules

- Keep signatures and examples aligned with implemented functions.
- Keep claims testable by `tests/execute/test_execute_pymdp_*.py`,
  integration tests, and
  `tests/execute/test_pymdp_1_0_0_upstream_api.py` (installed `Agent` API).
- Keep wording concise; avoid capability claims not exercised in code.