nardial 0.3.2__tar.gz → 0.4.1__tar.gz

{nardial-0.3.2 → nardial-0.4.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: nardial
-Version: 0.3.2
+Version: 0.4.1
 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
@@ -42,6 +42,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 +158,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 |
 
 ---
 
@@ -282,6 +284,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 +311,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 +355,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 +527,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 +640,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 +669,7 @@ 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` |
 
 ```json
 {
@@ -601,11 +769,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 +804,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 +884,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 +901,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 +982,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 +1036,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 +1050,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