new: inquire namespace to let the agent interactively ask questions to the user in a structured way.

Author: evilsocket

docs/assets/make_ns.py

@@ -31,6 +31,9 @@
 
             print(doc.strip())
             print()
+            print("<details>")
+            print("<summary><b>Show Tools</b></summary>")
+
             print("| Tool | Description |")
             print("|------|-------------|")
 
@@ -40,4 +43,5 @@
                     doc = doc.strip().replace("\n", "<br>")
                     print(f"| `{name}` | <pre>{doc}</pre> |")
 
-            print("")
+            print("</details>")
+            print()

docs/namespaces.md

@@ -6,9 +6,12 @@ Nerve offers a rich set of predefined tools, organized in namespaces, that the a
 
 Let the agent create its own tools in Python.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `create_tool` | <pre>Create a new tool or redefine an existing one by defining it as an annotated Python function.<br>    Use this tool to implement the missing functionalities you need to perform your task.</pre> |
+</details>
 
 ## computer
 
@@ -18,6 +21,8 @@ Let the agent create its own tools in Python.
 
 Computer use primitives for mouse, keyboard, and screen.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `get_cursor_position` | <pre>Get the current mouse position.</pre> |
@@ -31,48 +36,78 @@ Computer use primitives for mouse, keyboard, and screen.
 | `mouse_right_click` | <pre>Click the right mouse button at the current mouse position.</pre> |
 | `mouse_scroll` | <pre>Scroll the mouse wheel in the given direction.</pre> |
 | `screenshot` | <pre>Take a screenshot of the current screen.</pre> |
+</details>
 
 ## filesystem
 
 Read-only access primitives to the local filesystem.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `list_folder_contents` | <pre>List the contents of a folder on disk.</pre> |
 | `read_file` | <pre>Read the contents of a file from disk.</pre> |
+</details>
+
+## inquire
+
+Let the agent interactively ask questions to the user in a structured way.
+
+<details>
+<summary><b>Show Tools</b></summary>
+| Tool | Description |
+|------|-------------|
+| `ask_for_confirmation` | <pre>Ask a confirmation question to the user.</pre> |
+| `ask_for_multiple_choice` | <pre>Ask a multiple choice question to the user.</pre> |
+| `ask_for_single_choice` | <pre>Ask a single choice question to the user.</pre> |
+| `ask_question` | <pre>Ask a question to the user.</pre> |
+</details>
 
 ## reasoning
 
 Simulates the reasoning process at runtime.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `clear_thoughts` | <pre>If the reasoning process proved wrong, inconsistent or ineffective, clear your thoughts and start again.</pre> |
 | `think` | <pre>Adhere strictly to this reasoning framework, ensuring thoroughness, precision, and logical rigor.<br><br>    ## Problem Decomposition<br><br>    Break the query into discrete, sequential steps.<br>    Explicitly state assumptions and context.<br><br>    ## Stepwise Analysis<br><br>    Address each step individually.<br>    Explain the rationale, principles, or rules applied (e.g., mathematical laws, linguistic conventions).<br>    Use examples, analogies, or intermediate calculations to illustrate reasoning.<br><br>    ## Validation & Error Checking<br><br>    Verify logical consistency at each step.<br>    Flag potential oversights, contradictions, or edge cases.<br>    Confirm numerical accuracy (e.g., recompute calculations).<br><br>    ## Synthesis & Conclusion<br><br>    Integrate validated steps into a coherent solution.<br>    Summarize key insights and ensure the conclusion directly addresses the original query.</pre> |
+</details>
 
 ## shell
 
 Let the agent execute shell commands.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `shell` | <pre>Execute a shell command on the local computer and return the output. Non interactive shell with a timeout of 30 seconds.</pre> |
+</details>
 
 ## task
 
 Let the agent autonomously set the task as complete or failed.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `task_complete_success` | <pre>When your objective has been reached use this tool to set the task as complete.</pre> |
 | `task_failed` | <pre>Use this tool if you determine that the given goal or task is impossible given the information you have.</pre> |
+</details>
 
 ## time
 
 Provides tools for getting the current date and time and waiting for a given number of seconds.
 
+<details>
+<summary><b>Show Tools</b></summary>
 | Tool | Description |
 |------|-------------|
 | `current_time_and_date` | <pre>Get the current date and time.</pre> |
 | `wait` | <pre>Wait for a given number of seconds.</pre> |
+</details>
 

nerve/cli/run.py

@@ -29,15 +29,14 @@
 
 @cli.command(
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True, "help_option_names": ["-h", "--help"]},
-    no_args_is_help=True,
     help="Execute an agent or a workflow.",
 )
 def run(
     ctx: typer.Context,
     input_path: t.Annotated[
         pathlib.Path,
         typer.Argument(help="Agent or workflow to execute"),
-    ],
+    ] = pathlib.Path("."),
     generator: t.Annotated[
         str,
         typer.Option("--generator", "-g", help="Generator to use"),

nerve/generation/__init__.py

@@ -116,7 +116,7 @@ def _get_text_response(self, content: str) -> dict[str, t.Any]:
 
         return {
             "role": "user",
-            "content": "None of the tools were used.",
+            "content": "None of the tools were used, interact with the user by executing the existing tools.",
         }
 
     def _get_unknown_tool_response(self, tool_call_id: str, tool_name: str) -> dict[str, t.Any]:

nerve/models.py

@@ -66,6 +66,8 @@ class Configuration(BaseModel):
 
     # TODO: add a "precall" to call the tool when the agent is started
 
+    # TODO: document these fields.
+
     # used for versioning the agents
     version: str = "1.0.0"
     # the system prompt, the agent identity

nerve/tools/namespaces/__init__.py

@@ -1,2 +1 @@
 # TODO: browser namespace (playwright wrapper)
-# TODO: namespace with tools to prompt the user like the create command

nerve/tools/namespaces/inquire.py

@@ -0,0 +1,78 @@
+"""
+Let the agent interactively ask questions to the user in a structured way.
+"""
+
+from typing import Annotated
+
+import inquirer  # type: ignore
+from pydantic import Field
+
+
+def ask_question(
+    question: Annotated[
+        str,
+        Field(description="The question to ask the user.", examples=["What is your name?", "What is your age?"]),
+    ],
+) -> str:
+    """Ask a question to the user."""
+
+    print()
+    return str(inquirer.prompt([inquirer.Text("question", message=question)])["question"]).strip()
+
+
+def ask_for_confirmation(
+    question: Annotated[
+        str,
+        Field(
+            description="The question to ask the user.", examples=["Do you want to continue?", "Do you want to quit?"]
+        ),
+    ],
+    default: Annotated[bool, Field(description="The default answer to the question.", examples=[True, False])] = False,
+) -> str:
+    """Ask a confirmation question to the user."""
+
+    print()
+    return (
+        "YES" if inquirer.prompt([inquirer.Confirm("confirm", message=question, default=default)])["confirm"] else "NO"
+    )
+
+
+def ask_for_single_choice(
+    question: Annotated[
+        str,
+        Field(
+            description="The question to ask the user.",
+            examples=["What is your favorite color?", "What is your favorite food?"],
+        ),
+    ],
+    choices: Annotated[
+        list[str],
+        Field(description="The choices to offer the user.", examples=["red", "blue", "green"]),
+    ],
+) -> str:
+    """Ask a single choice question to the user."""
+
+    print()
+    return str(inquirer.prompt([inquirer.List("choice", message=question, choices=choices)])["choice"]).strip()
+
+
+def ask_for_multiple_choice(
+    question: Annotated[
+        str,
+        Field(
+            description="The question to ask the user.",
+            examples=["What are your favorite colors?", "What are your favorite foods?"],
+        ),
+    ],
+    choices: Annotated[
+        list[str],
+        Field(description="The choices to offer the user.", examples=["red", "blue", "green"]),
+    ],
+) -> str:
+    """Ask a multiple choice question to the user."""
+
+    print()
+    return ", ".join(
+        str(choice).strip()
+        for choice in inquirer.prompt([inquirer.Checkbox("choices", message=question, choices=choices)])["choices"]
+    )