nardial 0.3.3__tar.gz → 0.4.2__tar.gz

{nardial-0.3.3 → nardial-0.4.2}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: nardial
-Version: 0.3.3
+Version: 0.4.2
 Summary: Nardial Dialog System
 Author-email: Mike Ligthart <m.e.u.ligthart@vu.nl>
-Maintainer: Clara Fayyad, Landon Brown, Evelyne Prodescu
+Maintainer: Clara Fayyad, Landon Brown, Evelyne Prodescu, Eva Biesot
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: social-interaction-cloud
+Requires-Dist: pynput>=1.7
 Provides-Extra: google-tts
 Requires-Dist: social-interaction-cloud[google-tts]; extra == "google-tts"
 Provides-Extra: elevenlabs
@@ -42,6 +43,7 @@ It lets you author complete conversations declaratively in JSON, then drive them
 4. [Defining Dialogs in JSON](#defining-dialogs-in-json)
    - [Dialog Structure](#dialog-structure)
    - [Dialog Types](#dialog-types)
+     - [Custom dialog types](#custom-dialog-types)
    - [Move Types](#move-types)
    - [Key JSON Attributes](#key-json-attributes)
 5. [Demos / Creating a Session](#demos--creating-a-session)
@@ -157,23 +159,24 @@ NarDialPy is built around a set of provider protocols. Each protocol defines a r
 
 ### Available Providers
 
-| Role | Provider | Import path | Requires |
-|---|---|---|---|
-| **Device** | `DesktopAdapter` | `nardial.providers.device.desktop` | base |
-| | `PepperAdapter` | `nardial.providers.device.pepper` | base |
-| | `NaoAdapter` | `nardial.providers.device.nao` | base |
-| | `AlphaminiAdapter` | `nardial.providers.device.alphamini` | `social-interaction-cloud[alphamini]` |
-| **TTS** | `GoogleTTSProvider` | `nardial.providers.tts.google` | `nardial[google-tts]` |
-| | `ElevenLabsTTSProvider` | `nardial.providers.tts.elevenlabs` | `nardial[elevenlabs]` |
-| | `NaoqiTTSProvider` | `nardial.providers.tts.naoqi` | base (uses device's built-in TTS) |
-| | `NullTTSProvider` | `nardial.providers.tts.null` | base (prints to terminal) |
-| **NLU** | `DialogflowNLUProvider` | `nardial.providers.nlu.dialogflow` | `nardial[dialogflow]` |
-| | `WrittenKeywordNLUProvider` | `nardial.providers.nlu.written_keyword` | base (keyboard input) |
-| **LLM** | `OpenAIGPTProvider` | `nardial.providers.llm.openai_gpt` | `nardial[openai]` |
-| | `EchoLLMProvider` | `nardial.providers.llm.echo` | base (echoes user input) |
-| **Screen** | `ScreenProvider` / `SICScreenAdapter` / `PepperTabletScreenAdapter` | `nardial.providers.screen` | browser display via SIC webserver |
+| Role | Provider | Import path                                  | Requires |
+|---|---|----------------------------------------------|---|
+| **Device** | `DesktopAdapter` | `nardial.providers.device.desktop`           | base |
+| | `PepperAdapter` | `nardial.providers.device.pepper`            | base |
+| | `NaoAdapter` | `nardial.providers.device.nao`               | base |
+| | `AlphaminiAdapter` | `nardial.providers.device.alphamini`         | `social-interaction-cloud[alphamini]` |
+| | `ReachyMiniAdapter` | `nardial.providers.reachy_mini`              | `social-interaction-cloud[reachy-mini]` | 
+| **TTS** | `GoogleTTSProvider` | `nardial.providers.tts.google`               | `nardial[google-tts]` |
+| | `ElevenLabsTTSProvider` | `nardial.providers.tts.elevenlabs`           | `nardial[elevenlabs]` |
+| | `NaoqiTTSProvider` | `nardial.providers.tts.naoqi`                | base (uses device's built-in TTS) |
+| | `NullTTSProvider` | `nardial.providers.tts.null`                 | base (prints to terminal) |
+| **NLU** | `DialogflowNLUProvider` | `nardial.providers.nlu.dialogflow`           | `nardial[dialogflow]` |
+| | `WrittenKeywordNLUProvider` | `nardial.providers.nlu.written_keyword`      | base (keyboard input) |
+| **LLM** | `OpenAIGPTProvider` | `nardial.providers.llm.openai_gpt`           | `nardial[openai]` |
+| | `EchoLLMProvider` | `nardial.providers.llm.echo`                 | base (echoes user input) |
+| **Screen** | `ScreenProvider` / `SICScreenAdapter` / `PepperTabletScreenAdapter` | `nardial.providers.screen`                   | browser display via SIC webserver |
 | **Vector store** | `RedisVectorStoreProvider` | `nardial.providers.vector_store.redis_store` | base + running Redis |
-| | `NullVectorStoreProvider` | `nardial.providers.vector_store.null` | base |
+| | `NullVectorStoreProvider` | `nardial.providers.vector_store.null`        | base |
 
 ---
 
@@ -267,6 +270,37 @@ Then pass `device` and `tts` to `ConversationAgent` as above.
 
 ---
 
+### Pause and skip controls
+
+Bind keys to pause the interaction or to skip a listen that takes too long by passing `controls` in an `InteractionConfig`. Keys work globally (the terminal does not need focus), with or without `SessionManager`:
+
+```python
+from nardial.interaction_orchestrator import InteractionConfig
+
+agent = ConversationAgent(
+    ...,  # device and providers as in the setups above
+    int_config=InteractionConfig(
+        controls={
+            "start_paused": True,          # wait for the pause key before starting
+            "toggle_pause": ["space"],     # pause / resume
+            "skip_listen": ["s"],          # stop a listen that takes too long
+        },
+    ),
+)
+```
+
+| Setting | Effect |
+|---|---|
+| `toggle_pause` | Pauses the interaction. Speech in progress is stopped and spoken again from the beginning after resume. Listening in progress is stopped, what was heard so far is kept, and the dialog continues after the listen once resumed. Works in every dialog type, including LLM dialogs. |
+| `skip_listen` | Stops the current listen early. What was said so far is still recognised and used as the answer: Dialogflow gets a `StopListeningMessage`, and local Whisper gets an end-of-audio signal and then transcribes what it recorded (this can take a few seconds; Whisper waits up to 30 s for it, which a faster model can lower with `LocalWhisperNLUProvider(..., stop_grace_seconds=5)`). The written keyword provider cannot stop early and gives up after 3 seconds with an empty answer. |
+| `start_paused` | `true` makes the interaction wait for `toggle_pause` before it starts. |
+
+A question whose listen was stopped by a pause or skip is not asked again, even when the answer is empty: the dialog continues with whatever was heard, and an empty answer follows the move's `default_outcome`.
+
+Key names are single characters (`"p"`) or [pynput key names](https://pynput.readthedocs.io/en/latest/keyboard.html#pynput.keyboard.Key) (`"space"`, `"enter"`, `"f5"`). Moves that are not speech or listening (e.g. `timed_wait`, `wait_for_button`) are not paused; the pause takes effect at the next speech or listen.
+
+---
+
 ### Using SessionManager
 
 `SessionManager` wraps `ConversationAgent` and adds dialog loading, eligibility checking, and session state:
@@ -282,6 +316,20 @@ manager = SessionManager(
 manager.run()
 ```
 
+If a previous run crashed mid-session, pass `resume=True` to continue that same incomplete session (one whose `ended_at` is still `None`) instead of starting a new one — dialogs already completed in it are skipped:
+
+```python
+manager = SessionManager(
+    agent=agent,
+    dialog_file="dialogs/my_dialogs.json",
+    participant_id="user_42",
+    resume=True,
+)
+manager.run()
+```
+
+See [Developer Flow](docs/DEVELOPER_README.md) for more on session/state handling.
+
 ---
 
 ## Defining Dialogs in JSON
@@ -295,10 +343,11 @@ Every dialog has the following shared fields:
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `id` | string | ✅ | Unique identifier referenced in `session_agenda` and `dependencies` |
-| `type` | string | ✅ | Dialog type: `"functional"`, `"chitchat"`, `"narrative"`, or `"llm_based"` |
+| `type` | string | ✅ | Dialog type: `"functional"`, `"chitchat"`, `"narrative"`, `"llm_based"`, or a [custom type](#custom-dialog-types) |
 | `moves` | array | ✅ | Ordered list of move objects the robot will perform |
 | `dependencies` | array of strings | | Dialog IDs that must have been completed before this dialog may run |
 | `variable_dependencies` | array | | Variables that must exist in the user model before this dialog may run |
+| `prerequisites` | array | | Actions run just before the dialog's first move: call a registered Python function, or set user-model variables (see [below](#optional-top-level-prerequisites)) |
 
 Example: 
 ```json
@@ -338,6 +387,51 @@ Dialogs can define reusable character voices:
 - Each value must contain a `voice_settings` object.
 - `voice_settings` is validated at runtime against the active TTS provider.
 
+#### Optional Top-Level `prerequisites`
+
+Dialogs can list actions to run just before their first move, each time the dialog runs:
+
+```json
+{
+  "id": "multiplication",
+  "type": "chitchat",
+  "prerequisites": [
+    { "execute": "choose_math_level", "args": [true, false] , "skip_dialog":  true},
+    { "set_variable": { "math_left": 4, "math_right": 3 } }
+  ],
+  "moves": [
+    { "type": "say", "text": "What is %math_left% times %math_right%?" }
+  ]
+}
+```
+
+Each entry does one of two things:
+
+| Key | Value | What happens |
+|---|---|---|
+| `execute` | name of a registered function | Calls that Python function. Optional `args`: a list is passed as separate arguments (`[3, 4]` calls `f(3, 4)`), any other value as a single argument, and without `args` the function is called with none. |
+| `set_variable` | object | Merges the object into the user model, so its values can be used in `%variable%` placeholders and later dialogs. |
+
+In every prerequisite, `"skip_dialog` can be set to `true` of `false`, based on whether the dialog needs to be skipped if the prerequisite cannot be completed. `"skip_dialog:true` means that the dialog will be skipped if the prerequisite is not completed. If `"skip_dialog: false` is chosen, the dialog will still run, even if the prerequisite could not be completed. The default is `false`.
+Functions are registered in Python under the name used in `execute`, before the session runs:
+
+```python
+from nardial.mini_dialogs import MiniDialog
+
+@MiniDialog.register("choose_math_level")
+def choose_math_level(last_correct, needed_help):
+    if last_correct and not needed_help:
+        level = 2
+    else:
+        level = 1
+    return level
+
+```
+
+- Prerequisites run in the order listed, after the dialog has been picked. They can't change whether the dialog itself is eligible, only what happens once it runs.
+- Registered functions must be regular (not `async`) functions. They get only the `args` from the JSON, not the dialog or the user model.
+- If a function isn't registered or raises an error, the error is printed and the remaining prerequisites and the dialog still run.
+
 ---
 
 #### 1.`functional`
@@ -465,6 +559,95 @@ A fully LLM-driven dialog where the robot and user engage in a free-form multi-t
 }
 ```
 
+#### Custom dialog types
+
+You can define your own dialog type in JSON. A custom type is based on an existing type and changes the rules that decide when its dialogs may run.
+
+Type definitions go in their own JSON file (or a directory of them), separate from your dialogs. Mixing them is an error: a type definition in a dialog file, or a dialog in a types file, is reported and skipped. Pass the types file to `SessionManager` as `dialog_types_path`. It is loaded before the dialogs, so dialogs can use the new types:
+
+```python
+manager = SessionManager(
+    session_agenda=[...],
+    agent=agent,
+    dialog_types_path="dialog_types/my_types.json",
+    dialog_json_path="dialog_json/my_dialogs.json",
+)
+```
+
+Without `SessionManager`, call `load_dialog_types(path)` (from `nardial.authoring`) before loading the dialogs. Within the types file(s), the order of definitions doesn't matter, even when one type extends another.
+
+A type definition looks like this:
+
+```json
+{
+  "define_type": "repeatable_chitchat",
+  "extends": "chitchat",
+  "description": "Chitchat that may come back in later sessions, but runs at most once per session.",
+  "remove_rules": ["exclude_if_seen"],
+  "add_rules": [{ "rule": "exclude_if_seen", "scope": "session" }]
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `define_type` | string | ✅ | Name of the new type, used as `type` in dialogs |
+| `extends` | string | ✅ | Type it is based on: a built-in type or another custom type |
+| `description` | string | | Free-text description |
+| `remove_rules` | array of strings | | Names of the base type's rules to drop |
+| `add_rules` | array | | Rules to add: a rule name, or an object with `"rule"` plus that rule's settings |
+
+Dialogs of the new type use the same fields as dialogs of the type it extends:
+
+```json
+{
+  "id": "music_lately",
+  "type": "repeatable_chitchat",
+  "topics": ["music"],
+  "moves": [{ "type": "say", "text": "What music have you been listening to lately?" }]
+}
+```
+
+They are also picked by the same agenda slots. For example, a `chitchat_slot` can choose a `repeatable_chitchat` dialog.
+
+**Built-in types and their rules:**
+
+| Type | Rules |
+|---|---|
+| `functional` | `dependency_met` |
+| `narrative` | `exclude_if_seen`, `dependency_met`, `variable_dependency_met`, `narrative_ordering` |
+| `chitchat` | `exclude_if_seen`, `dependency_met`, `variable_dependency_met` |
+| `llm_based` | `exclude_if_seen`, `dependency_met`, `variable_dependency_met` |
+
+**Available rules.** A dialog may run only when all of its type's rules allow it.
+
+| Rule | Settings | Allows the dialog to run when |
+|---|---|---|
+| `exclude_if_seen` | `scope`: `"participant"` (default) or `"session"` | it hasn't been completed before (by this participant, or in this session) |
+| `dependency_met` | | every dialog in its `dependencies` has been completed |
+| `variable_dependency_met` | | every required variable in its `variable_dependencies` is set in the user model |
+| `narrative_ordering` | | every earlier `position` in its `thread` has been completed |
+
+**Your own rules.** Any other rule is written in Python and registered under a name, which `add_rules` can then use. Settings from the JSON are passed to the constructor:
+
+```python
+from nardial.eligibility import EligibilityRule, register_rule
+
+@register_rule("from_session")
+class FromSessionRule(EligibilityRule):
+    def __init__(self, min):
+        self.min = min
+
+    def is_eligible(self, dialog, context):
+        # context.session_index: session number starting at 1, or None when unknown
+        return context.session_index is not None and context.session_index >= self.min
+```
+
+```json
+{ "define_type": "returning_chitchat", "extends": "chitchat", "add_rules": [{ "rule": "from_session", "min": 2 }] }
+```
+
+Import the module that registers the rule before loading your dialogs. A rule can read `context.user_model`, `context.completed_ids`, `context.session_completed_ids`, `context.session_index` and `context.registry`. See `docs/DEVELOPER_README.md` for more, including defining types directly in Python.
+
 ---
 
 ### Move Types
@@ -489,6 +672,22 @@ Speaks a piece of text. Variable placeholders (`%variable_name%`) are replaced a
 
 ---
 
+#### `say_options`
+
+Speaks one randomly chosen response from a predefined list.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | string | ✅ | `"say_options"` |
+| `options` | array of strings | ✅ | Candidate utterances to choose from at runtime |
+| `character` | string | | Optional character name from top-level `characters` |
+
+```json
+{ "type": "say_options", "options": ["Hi!", "Hello!", "Hey there!"] }
+```
+
+---
+
 #### `ask_open`
 
 Asks a free-text question and listens for any spoken reply. The answer can be stored in a variable and used to drive branching.
@@ -502,6 +701,8 @@ Asks a free-text question and listens for any spoken reply. The answer can be st
 | `default_outcome` | string | | Outcome label when no answer or no match is found |
 | `add_interest_from_answer` | boolean | | If `true`, adds the answer to the user's topics of interest |
 | `llm_followup` | string | | System prompt for an LLM-generated follow-up sentence after the user replies |
+| `llm_extract_entity` | boolean | | If `true`, the LLM extracts the key entity from the answer (e.g. `"dog"` from `"my favorite animal is a dog"`) before it is stored; unrelated answers store nothing. Default `false` |
+| `timeout` | number | | Seconds to listen for an answer. Defaults to `InteractionConfig(listen_timeout=...)` (10 s) |
 
 ```json
 {
@@ -527,6 +728,7 @@ Asks a yes/no question. The detected intent (`"yes"`, `"no"`, `"dontknow"`) driv
 | `default_outcome` | string | | Outcome label used as fallback |
 | `add_interest` | string | | Topic added to interest list when the user answers `"yes"` |
 | `llm_followup` | string | | System prompt for an LLM-generated follow-up sentence |
+| `timeout` | number | | Seconds to listen for an answer. Defaults to `InteractionConfig(listen_timeout=...)` (10 s) |
 
 ```json
 {
@@ -555,6 +757,7 @@ Presents a multiple-choice question. The selected option drives branching and ca
 | `default_outcome` | string | | Outcome label when nothing matches |
 | `add_interest_from_variable` | string | | After storing, adds the named variable's value as a topic of interest |
 | `llm_followup` | string | | System prompt for an LLM-generated follow-up sentence |
+| `timeout` | number | | Seconds to listen for an answer. Defaults to `InteractionConfig(listen_timeout=...)` (10 s) |
 
 ```json
 {
@@ -601,11 +804,12 @@ Starts a multi-turn LLM-driven exchange *within* an otherwise scripted dialog. U
 
 Selects and executes a list of sub-moves based on the current outcome or the value of a user model variable.
 
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `type` | string | ✅ | `"branch"` |
-| `on` | string | ✅ | `"outcome"` to branch on the last question's result, or a variable name to branch on its stored value |
-| `cases` | object | ✅ | Maps condition values to arrays of sub-moves |
+| Field       | Type | Required | Description                                                                                                                                                                                        |
+|-------------|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `type`      | string | ✅ | `"branch"`                                                                                                                                                                                         |
+| `on`        | string | ✅ | `"outcome"` to branch on the last question's result, `"variables"` to branch based on whether to variabels in the user model have the same value, or a variable name to branch on its stored value |
+| `cases`     | object | ✅ | Maps condition values to arrays of sub-moves                                                                                                                                                       |
+| `variables` | list | | In case of branching on `"variables"`, a list of the variables that need to be compared | 
 
 ```json
 {
@@ -635,6 +839,20 @@ Branching on a stored variable (e.g. to react to an answer from an earlier dialo
 }
 ```
 
+Branching on comparison of two stored variables (e.g. to check whether a given answer is correct). Chooses branch "true" if the values of the variables are the same, branch "false" if not.
+
+```json
+{
+  "type": "branch",
+  "on": "variables",
+  "variables": ["given_answer", "correct_answer"],
+  "cases": {
+    "true": [{ "type":  "say", "text":  "That's correct!"}],
+    "false": [{ "type":  "say", "text":  "That's incorrect. Let's try again."}]
+  }
+}
+```
+
 ---
 
 #### `play`
@@ -701,14 +919,15 @@ Pause execution for a fixed duration before proceeding to the next move. Useful
 
 Suspend dialog execution until a matching web input event arrives or until a timeout elapses. The web UI can present buttons or a short input and emit `web_input` events which this move listens for.
 
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `type` | string | ✅ | `"wait_for_web_input"` |
-| `prompt` | string | | Hint text shown in the web UI (not spoken) |
+| Field | Type | Required | Description                                                                     |
+|---|---|---|---------------------------------------------------------------------------------|
+| `type` | string | ✅ | `"wait_for_web_input"`                                                          |
+| `prompt` | string | | Hint text shown in the web UI (not spoken)                                      |
 | `options` | array of strings | | Accepted `value` strings from the web event (if omitted, any value is accepted) |
-| `timeout` | number | | Seconds to wait before falling back (omit for indefinite wait) |
-| `outcomes` | object | | Maps option value → outcome label for branching |
-| `default_outcome` | string | | Outcome used on timeout or when no event matches |
+| `timeout` | number | | Seconds to wait before falling back (omit for indefinite wait)                  |
+| `outcomes` | object | | Maps option value → outcome label for branching                                 |
+| `default_outcome` | string | | Outcome used on timeout or when no event matches                                |
+| `set_variable` | string | | Stores the user's choice in the user model                                      |
 
 ```json
 {
@@ -717,7 +936,8 @@ Suspend dialog execution until a matching web input event arrives or until a tim
   "options": ["smile","thumbs","surprised"],
   "timeout": 15,
   "outcomes": {"smile": "picked_smile"},
-  "default_outcome": "no_choice"
+  "default_outcome": "no_choice",
+  "set_variable": "sticker"
 }
 ```
 
@@ -797,6 +1017,49 @@ Clear the display (show a blank/black screen). No parameters — the next displa
 
 ---
 
+#### `keyboard_input`
+
+Display keyboard input on screen. Suspend dialog execution until keyboard input is given or until a timeout elapses.
+
+| Field | Type | Required | Description                                                    |
+|---|---|---|----------------------------------------------------------------|
+| `type` | string | ✅ | `"keyboard_input"`                                             |
+| `prompt` | string | | Hint text shown in the web UI (not spoken)                     |
+| `timeout` | number | | Seconds to wait before falling back (omit for indefinite wait) |
+| `outcomes` | object | | Maps option value → outcome label for branching                |
+| `default_outcome` | string | | Outcome used on timeout or when no event matches               |
+| `set_variable` | string | | Stores the user's choice in the user model                     |
+
+```json
+{
+  "type": "keyboard_input",
+  "prompt": "How old are you?",
+  "timeout": 15,
+  "default_outcome": "no_age_given",
+  "set_variable": "age"
+}
+```
+
+---
+
+#### `go_to_dialog`
+
+Move to a specified new minidialog.
+
+| Field             | Type | Required | Description                                                    |
+|-------------------|---|----------|----------------------------------------------------------------|
+| `type`            | string | ✅        | `"go_to_dialog"`                                               |
+| `dialog_id`       | string |✅          | ID of the dialog to go to                                      |
+
+```json
+{
+  "type": "go_to_dialog",
+  "dialog_id": "favorite_animal"
+}
+```
+
+---
+
 ### Key JSON Attributes
 
 | Attribute | Where used | Description |
@@ -808,11 +1071,13 @@ Clear the display (show a blank/black screen). No parameters — the next displa
 
 All you need is a minimal Python script that wires up the device, loads the dialog JSON, and runs the session. You can follow the included demos to get started quickly.
 
-Two ready-to-run demos are included in the `examples/` directory:
+Ready-to-run demos are included in the `examples/` directory:
 * Demo 1 — General Conversation (`demo_general_conversation.py`): A simple four-step conversation using a mix of narrative and functional dialogs
 * Demo 2 — Structured Conversation (`demo_structured_conversation.py`): A more complete example that demonstrates all dialog types and move types, including `ask_llm`, `play`, `motion_sequence`, and `animation`
 * Demo 3 — Screen Display (`demo_screen_provider.py`): Shows the browser-based screen UI with transcripts, images, iframes, HTML snippets, buttons, and text input
 * Demo 4 — Pepper Tablet (`demo_pepper_tablet.py`): Uses the same screen UI on Pepper's tablet through the SIC webserver
+* Demo 5 — Agenda System (`demo_agenda_system.py`): Uses every agenda-item type (`narrative_slot`, `chitchat_slot`, `functional_slot`, `llm_dialog_ref`, plain dialog ids) so `SessionManager` picks the next dialog dynamically instead of following a fixed list — see the [Agenda System Guide](docs/AGENDA_SYSTEM_GUIDE.md) for a plain-language walkthrough
+* Demo 6 — Custom Dialog Type (`demo_custom_dialog_type.py`): Writes a custom eligibility rule in Python and defines two new dialog types in JSON (see [Custom dialog types](#custom-dialog-types)): a chitchat that comes back every session, and one that only runs for participants who said they have a pet
 
 You can find additional demos in the [SIC Applications repository](https://github.com/Social-AI-VU/sic_applications/tree/main/demos/nardial)
 
@@ -820,6 +1085,8 @@ You can find additional demos in the [SIC Applications repository](https://githu
 
 ## Development
 
+For an architecture-level explanation of how JSON dialogs become running conversations, see [Developer Flow](docs/DEVELOPER_README.md). If you're building an application and want to understand dynamic session agendas rather than runtime internals, see the [Agenda System Guide](docs/AGENDA_SYSTEM_GUIDE.md) instead.
+
 Run tests from the repository root:
 
 ```bash