Add minimal experiment tutorial example

Author: evilrobotxoxo

docs/source/user_guide.rst

@@ -33,5 +33,6 @@ are still in planning or early development.
 
    user_guide_first_run
    user_guide_sample_task
+   user_guide_minimal_experiment
    user_guide_outputs
    user_guide_troubleshooting

docs/source/user_guide_minimal_experiment.rst

@@ -0,0 +1,173 @@
+Minimum Experiment Code
+=======================
+
+Why This Example Exists
+-----------------------
+
+After you run the sample task once, the next useful question is usually:
+
+``What is the smallest amount of code I need to write my own experiment?``
+
+The answer is **not** "put everything in one script and call random BehavBox
+methods directly." That would be shorter, but it would teach the wrong pattern.
+
+The supported minimum pattern is:
+
+1. one small task module containing only task logic
+2. one runner script for local mock use
+3. one runner script for a headless Raspberry Pi (RPi) over Secure Shell (SSH)
+4. one small session-configuration helper
+
+This keeps the code small while still using the current supported lifecycle.
+
+Where The Example Lives
+-----------------------
+
+The tracked example files are:
+
+- ``sample_tasks/minimal_experiment/task.py``
+- ``sample_tasks/minimal_experiment/session_config.py``
+- ``sample_tasks/minimal_experiment/run_mock.py``
+- ``sample_tasks/minimal_experiment/run_pi.py``
+
+The Shared Session Configuration
+--------------------------------
+
+The session helper builds the ``session_info`` dictionary in one place:
+
+.. literalinclude:: ../../sample_tasks/minimal_experiment/session_config.py
+   :language: python
+   :lines: 1-67
+
+Why it is written this way:
+
+- output paths are centralized
+- the mock and headless-Pi versions stay consistent
+- the task code does not need to know where files should be written
+- the only real difference between the two modes is whether audio stays mocked
+
+The Minimal Task
+----------------
+
+The task module contains the experiment logic itself:
+
+.. literalinclude:: ../../sample_tasks/minimal_experiment/task.py
+   :language: python
+
+What this task does:
+
+- plays one cue
+- opens one response window
+- watches for one response event
+- optionally delivers reward
+- stops cleanly after a response or after the response window expires
+
+Why it is written this way:
+
+- ``prepare_task()`` holds setup that belongs to the task, not to the runner
+- ``start_task()`` starts the experiment by entering the first phase
+- ``handle_event()`` reacts only to relevant input events
+- ``update_task()`` advances the finite state machine (FSM) based on time
+- ``finalize_task()`` returns a small summary that becomes
+  ``final_task_state.json``
+
+This is the smallest useful pattern that still matches the current task API.
+
+Run It Locally In Mock Mode
+---------------------------
+
+Use this version on your local machine when you want the browser mock user
+interface (UI).
+
+The runner code is:
+
+.. literalinclude:: ../../sample_tasks/minimal_experiment/run_mock.py
+   :language: python
+
+Run it with:
+
+.. code-block:: bash
+
+   cd /Users/lukesjulson/codex/RPi4_refactor/targets/RPi4_behavior_boxes_hardware
+   uv run python -m sample_tasks.minimal_experiment.run_mock --session-tag tutorial_minimal
+
+What is specific to local mock mode:
+
+- it forces mock mode with ``BEHAVBOX_FORCE_MOCK=1``
+- it starts the browser mock UI automatically
+- it tells you to pulse ``lick_3`` in the browser
+
+This is the right choice when:
+
+- you are working on a desktop or laptop
+- you want to test task flow without real hardware
+- you want to debug the task logic first
+
+Run It On A Headless Pi Over SSH
+--------------------------------
+
+Use this version when you are logged into a real box over SSH and want the
+responses to come from the physical hardware.
+
+The runner code is:
+
+.. literalinclude:: ../../sample_tasks/minimal_experiment/run_pi.py
+   :language: python
+
+Example command on the Pi:
+
+.. code-block:: bash
+
+   cd ~/behavbox/RPi_behavior_boxes_hardware
+   uv run python -m sample_tasks.minimal_experiment.run_pi \
+     --output-root ~/behavbox_runs \
+     --session-tag tutorial_minimal
+
+What is specific to the headless-Pi version:
+
+- it does **not** force mock mode
+- it disables automatic mock-UI startup
+- it assumes inputs come from the real box
+
+This is the right choice when:
+
+- you are connected to a headless Pi over SSH
+- you want a real hardware run
+- you do not expect a local browser control panel to appear automatically
+
+Why There Are Two Runner Files
+------------------------------
+
+This split is intentional.
+
+The mock and headless-Pi versions should not be hidden behind one opaque flag,
+because users need to understand which environment they are running in:
+
+- local mock mode is for safe local testing with a browser UI
+- headless Pi mode is for real box execution over SSH
+
+If those modes are mixed together carelessly, users end up not knowing whether
+they are testing their code or their hardware.
+
+What To Copy For Your Own Task
+------------------------------
+
+If you want to start a new task, copy these pieces:
+
+1. ``task.py``
+2. ``session_config.py``
+3. one runner script that matches how you plan to work
+
+Then change only the task logic first:
+
+- cue selection
+- response event
+- stop condition
+- reward rule
+
+Do **not** start by rewriting the runner or bypassing ``TaskRunner`` unless you
+have a clear reason. The runner is what gives you:
+
+- consistent startup and shutdown
+- standard task artifacts
+- a path that still matches the current hardware repo architecture

sample_tasks/minimal_experiment/__init__.py

@@ -0,0 +1,2 @@
+"""Minimal lifecycle-based experiment example for end-user tutorials."""
+

sample_tasks/minimal_experiment/run_mock.py

@@ -0,0 +1,68 @@
+"""Run the minimal tutorial experiment locally in mock mode."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from box_runtime.behavior.behavbox import BehavBox
+from box_runtime.mock_hw.server import ensure_server_running
+from sample_tasks.common.runner import TaskRunner
+from sample_tasks.minimal_experiment.session_config import build_mock_session_info
+from sample_tasks.minimal_experiment import task as minimal_task
+
+
+def configure_mock_environment() -> None:
+    """Configure environment variables for local mock-mode tutorial runs."""
+
+    os.environ["BEHAVBOX_FORCE_MOCK"] = "1"
+    os.environ["BEHAVBOX_MOCK_UI_AUTOSTART"] = "1"
+
+
+def main() -> int:
+    """Run the minimal experiment locally with the browser mock UI.
+
+    Returns:
+    - ``exit_code``: zero on clean completion
+    """
+
+    parser = argparse.ArgumentParser(description="Run the minimal experiment locally in mock mode.")
+    parser.add_argument("--output-root", default="tmp_task_runs", help="Directory root for task outputs.")
+    parser.add_argument("--session-tag", default="minimal_experiment_session", help="Basename for the session directory.")
+    parser.add_argument("--max-duration-s", type=float, default=30.0, help="Maximum session duration in seconds.")
+    parser.add_argument("--reward-on-response", action="store_true", help="Deliver reward when the response event is detected.")
+    args = parser.parse_args()
+
+    configure_mock_environment()
+
+    output_root = Path(args.output_root).resolve()
+    output_root.mkdir(parents=True, exist_ok=True)
+    session_info = build_mock_session_info(output_root, args.session_tag)
+    mock_url = ensure_server_running()
+    print(f"Mock hardware UI: {mock_url}")
+    print("This is the local mock workflow. Open the browser UI and pulse lick_3 to respond.")
+
+    runner = TaskRunner(
+        box=BehavBox(session_info),
+        task=minimal_task,
+        task_config={
+            "max_duration_s": float(args.max_duration_s),
+            "reward_on_response": bool(args.reward_on_response),
+        },
+    )
+
+    try:
+        final_state = runner.run()
+    except KeyboardInterrupt:
+        runner.stop(reason="keyboard_interrupt")
+        final_state = runner.finalize()
+
+    print(f"Final task state written to: {Path(session_info['dir_name']) / 'final_task_state.json'}")
+    print(final_state)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

sample_tasks/minimal_experiment/run_pi.py

@@ -0,0 +1,69 @@
+"""Run the minimal tutorial experiment on a headless Raspberry Pi over SSH."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from box_runtime.behavior.behavbox import BehavBox
+from sample_tasks.common.runner import TaskRunner
+from sample_tasks.minimal_experiment.session_config import build_headless_pi_session_info
+from sample_tasks.minimal_experiment import task as minimal_task
+
+
+def configure_headless_pi_environment() -> None:
+    """Configure environment variables for a real headless Pi run.
+
+    The real Pi runner should not force mock mode. It also should not try to
+    auto-start the browser mock UI.
+    """
+
+    os.environ.pop("BEHAVBOX_FORCE_MOCK", None)
+    os.environ["BEHAVBOX_MOCK_UI_AUTOSTART"] = "0"
+
+
+def main() -> int:
+    """Run the minimal experiment on a headless Raspberry Pi.
+
+    Returns:
+    - ``exit_code``: zero on clean completion
+    """
+
+    parser = argparse.ArgumentParser(description="Run the minimal experiment on a headless Raspberry Pi.")
+    parser.add_argument("--output-root", default="~/behavbox_runs", help="Directory root for task outputs on the Pi.")
+    parser.add_argument("--session-tag", default="minimal_experiment_session", help="Basename for the session directory.")
+    parser.add_argument("--max-duration-s", type=float, default=30.0, help="Maximum session duration in seconds.")
+    parser.add_argument("--reward-on-response", action="store_true", help="Deliver reward when the response event is detected.")
+    args = parser.parse_args()
+
+    configure_headless_pi_environment()
+
+    output_root = Path(args.output_root).expanduser().resolve()
+    output_root.mkdir(parents=True, exist_ok=True)
+    session_info = build_headless_pi_session_info(output_root, args.session_tag)
+    print("This is the headless Raspberry Pi workflow.")
+    print("Run it over SSH. Responses come from the physical box inputs, not the browser mock UI.")
+
+    runner = TaskRunner(
+        box=BehavBox(session_info),
+        task=minimal_task,
+        task_config={
+            "max_duration_s": float(args.max_duration_s),
+            "reward_on_response": bool(args.reward_on_response),
+        },
+    )
+
+    try:
+        final_state = runner.run()
+    except KeyboardInterrupt:
+        runner.stop(reason="keyboard_interrupt")
+        final_state = runner.finalize()
+
+    print(f"Final task state written to: {Path(session_info['dir_name']) / 'final_task_state.json'}")
+    print(final_state)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())