csp-bot 2.0.3__tar.gz → 2.0.4__tar.gz

{csp_bot-2.0.3 → csp_bot-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: csp-bot
-Version: 2.0.3
+Version: 2.0.4
 Summary: Reactive chat bot framework
 Project-URL: Repository, https://github.com/Point72/csp-bot
 Project-URL: Homepage, https://github.com/Point72/csp-bot

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/__init__.py

@@ -11,7 +11,7 @@ Key features:
 - Support for Slack, Symphony, and Discord
 """
 
-__version__ = "2.0.3"
+__version__ = "2.0.4"
 
 # Re-export chatom types for convenience
 from chatom import Channel, Message, User

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/commands/agent.py

@@ -381,6 +381,9 @@ class AgentCommand(ReplyCommand):
         model_name = kwargs.pop("model_name", None)
         if model_name is not None:
             self.model_name = model_name
+        root_prompt = kwargs.pop("root_prompt", None)
+        if root_prompt is not None:
+            self.root_prompt = root_prompt
         self.mcp_servers = [MCPServerConfig.model_validate(config) for config in kwargs.pop("mcp_servers", [])]
 
     @classmethod
@@ -886,7 +889,8 @@ class AgentCommandModel(BaseCommandModel):
     command: type[AgentCommand]
     model_name: str = "claude-sonnet-4-6"
     mcp_servers: list[MCPServerConfig] = Field(default_factory=list)
+    root_prompt: str | None = None
 
     def create_command(self) -> AgentCommand:
         """Create the configured agent command."""
-        return self.command(model_name=self.model_name, mcp_servers=self.mcp_servers)
+        return self.command(model_name=self.model_name, mcp_servers=self.mcp_servers, root_prompt=self.root_prompt)

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/commands/base.py

@@ -46,6 +46,10 @@ class BaseCommand(ABC):
         """Return the help text for the command."""
         ...
 
+    def usage(self) -> str:
+        """Return optional command syntax, without a label."""
+        return ""
+
     @abstractmethod
     def num_recipients(self) -> int:
         """Return how many users this command can tag.

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/commands/framework.py

@@ -31,7 +31,7 @@ _COMMAND_REGISTRY: dict[str, CommandEntry] = {}
 class CommandEntry:
     """Internal registry entry for a command."""
 
-    __slots__ = ("backends", "handler", "help", "is_class", "name")
+    __slots__ = ("backends", "handler", "help", "is_class", "name", "usage")
 
     def __init__(
         self,
@@ -40,18 +40,22 @@ class CommandEntry:
         handler: Any,
         backends: list[str] | None = None,
         is_class: bool = False,
+        usage: str = "",
     ):
         self.name = name
         self.help = help
         self.handler = handler
         self.backends = backends or []
         self.is_class = is_class
+        self.usage = usage
 
 
 def command(
     name: str,
     help: str = "",
     backends: list[str] | None = None,
+    *,
+    usage: str = "",
 ) -> Callable:
     """Decorator to register a function as a bot command.
 
@@ -67,6 +71,7 @@ def command(
         name: The command name (e.g. "echo" for /echo).
         help: Help text shown by the /help command.
         backends: List of backends this command supports. Empty = all.
+        usage: Optional command syntax, without a label.
 
     Returns:
         The original function, registered in the global command registry.
@@ -85,12 +90,14 @@ def command(
             handler=fn,
             backends=backends,
             is_class=False,
+            usage=usage,
         )
         _COMMAND_REGISTRY[name] = entry
         # Stash metadata on the function for introspection
         fn._command_name = name
         fn._command_help = help
         fn._command_backends = backends or []
+        fn._command_usage = usage
         return fn
 
     return decorator
@@ -133,6 +140,9 @@ class Command(BaseModel):
     help: str = ""
     """Help text shown by the /help command."""
 
+    usage: str = ""
+    """Optional command syntax, without a label."""
+
     backends: list[str] = Field(default_factory=list)
     """Backends this command supports. Empty = all."""
 

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/commands/help.py

@@ -29,8 +29,14 @@ def _command_name(runner: Any) -> str:
 
 def _command_help(runner: Any) -> str:
     if isinstance(runner, BaseCommand):
-        return runner.help()
-    return getattr(runner, "help", "") or ""
+        description = runner.help()
+        usage = runner.usage()
+    else:
+        description = getattr(runner, "help", "") or ""
+        usage = getattr(runner, "usage", "") or ""
+    if not usage:
+        return description
+    return f"{description} Syntax: {usage}" if description else f"Syntax: {usage}"
 
 
 def _render_table_help(rows: list, backend: str) -> str:

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/commands/legacy.py

@@ -46,6 +46,10 @@ class LegacyCommandAdapter:
     def help(self) -> str:
         return self._command.help()
 
+    @property
+    def usage(self) -> str:
+        return self._command.usage()
+
     @property
     def backends(self) -> list[str]:
         return self._command.backends()

{csp_bot-2.0.3 → csp_bot-2.0.4}/csp_bot/tests/test_agent_command.py

@@ -180,6 +180,36 @@ class TestGetModel:
 
 
 class TestAgentCommandModel:
+    def test_creates_command_with_configured_root_prompt(self, bot_command):
+        model = AgentCommandModel(command=ConcreteAgentCommand, root_prompt="Use the project handbook for project questions.")
+
+        command = model.create_command()
+
+        assert model.root_prompt is not None
+        assert command.root_prompt == model.root_prompt
+        assert command.build_root_prompt(bot_command) == model.root_prompt
+        assert command._prompt_prefix(bot_command).startswith(model.root_prompt)
+
+    @pytest.mark.parametrize(
+        "configured,expected",
+        [(None, "Default project context."), ("", ""), ("Custom project context.", "Custom project context.")],
+    )
+    def test_root_prompt_preserves_defaults_or_uses_explicit_override(self, configured, expected):
+        class DefaultPromptCommand(ConcreteAgentCommand):
+            root_prompt = "Default project context."
+
+        model = AgentCommandModel(command=DefaultPromptCommand, root_prompt=configured)
+
+        assert model.create_command().root_prompt == expected
+        assert DefaultPromptCommand.root_prompt == "Default project context."
+
+    def test_root_prompt_is_instance_specific(self):
+        command = ConcreteAgentCommand(root_prompt="Custom project context.")
+
+        assert command.root_prompt == "Custom project context."
+        assert ConcreteAgentCommand().root_prompt == ""
+        assert ConcreteAgentCommand.root_prompt == ""
+
     def test_creates_command_with_configured_model_name(self):
         model = AgentCommandModel(command=ConcreteAgentCommand, model_name="github-copilot:test-model")
 

csp_bot-2.0.4/csp_bot/tests/test_help_command.py

@@ -0,0 +1,115 @@
+"""Tests for help command rendering."""
+
+from types import SimpleNamespace
+
+import pytest
+from chatom import Message, User
+
+from csp_bot.commands.echo import EchoCommand
+from csp_bot.commands.framework import Command, clear_registry, command, get_registered_commands
+from csp_bot.commands.help import HelpCommand
+from csp_bot.commands.legacy import LegacyCommandAdapter
+from csp_bot.structs import BotCommand, CommandVariant
+
+
+def _command(backend: str) -> BotCommand:
+    return BotCommand(
+        command="help",
+        args=(),
+        source=User(id="user1"),
+        targets=(),
+        channel_id="channel1",
+        channel_name="general",
+        backend=backend,
+        variant=CommandVariant.REPLY,
+        message=Message(id="msg1", content="!help"),
+        delay=None,
+        schedule="",
+        times_run=0,
+    )
+
+
+def _commands():
+    return {
+        "ask": SimpleNamespace(name="Ask", help="Ask <anything> & get an answer", backends=[]),
+        "help": SimpleNamespace(name="Help", help="Get help with bot commands", backends=[]),
+    }
+
+
+def test_help_discord_uses_list_not_markdown_table() -> None:
+    result = HelpCommand().execute(_command("discord"), _commands())
+
+    assert result.content.startswith("**Bot Commands Help**")
+    assert "- `/ask` **Ask**: Ask <anything> & get an answer" in result.content
+    assert "| Command" not in result.content
+
+
+def test_help_slack_uses_list_not_code_block_table() -> None:
+    result = HelpCommand().execute(_command("slack"), _commands())
+
+    assert result.content.startswith("*Bot Commands Help*")
+    assert "- `/ask` *Ask*: Ask <anything> & get an answer" in result.content
+    assert "```" not in result.content
+
+
+def test_help_telegram_uses_supported_html_list() -> None:
+    result = HelpCommand().execute(_command("telegram"), _commands())
+
+    assert result.content.startswith("<b>Bot Commands Help</b>")
+    assert "- <code>/ask</code> <b>Ask</b>: Ask &lt;anything&gt; &amp; get an answer" in result.content
+    assert "<table>" not in result.content
+
+
+def test_help_symphony_keeps_table_rendering() -> None:
+    result = HelpCommand().execute(_command("symphony"), _commands())
+
+    assert "<h3>Bot Commands Help</h3>" in result.content
+    assert "<table>" in result.content
+
+
+@pytest.mark.parametrize("backend", ["discord", "slack", "telegram", "symphony"])
+@pytest.mark.parametrize("runner_kind", ["base", "adapter", "metadata", "decorated", "stateful"])
+def test_help_renders_optional_usage_after_description(backend, runner_kind):
+    class UsageCommand(EchoCommand):
+        def help(self) -> str:
+            return "Echo a message."
+
+        def usage(self) -> str:
+            return "/echo message"
+
+    if runner_kind == "base":
+        runner = UsageCommand()
+    elif runner_kind == "adapter":
+        runner = LegacyCommandAdapter(UsageCommand())
+    elif runner_kind == "metadata":
+        runner = SimpleNamespace(name="Echo", help="Echo a message.", usage="/echo message", backends=[])
+    elif runner_kind == "stateful":
+        runner = Command(name="Echo", help="Echo a message.", usage="/echo message")
+    else:
+        clear_registry()
+        try:
+
+            @command(name="echo", help="Echo a message.", usage="/echo message")
+            def echo(context):
+                return context.args_text
+
+            runner = get_registered_commands()["echo"]
+        finally:
+            clear_registry()
+
+    result = HelpCommand().execute(_command(backend), {"echo": runner})
+    assert "Echo a message. Syntax: /echo message" in result.content
+    assert result.content.count("Syntax:") == 1
+
+
+def test_help_only_base_command_keeps_existing_output():
+    runner = EchoCommand()
+    assert runner.usage() == ""
+    result = HelpCommand().execute(_command("discord"), {"echo": runner})
+    assert result.content.endswith(f"- `/echo` **{runner.name()}**: {runner.help()}")
+
+
+def test_help_renders_usage_without_description():
+    runner = Command(name="Echo", usage="/echo message")
+    result = HelpCommand().execute(_command("discord"), {"echo": runner})
+    assert result.content.endswith("- `/echo` **Echo**: Syntax: /echo message")

{csp_bot-2.0.3 → csp_bot-2.0.4}/pyproject.toml

@@ -12,7 +12,7 @@ authors = [
 description = "Reactive chat bot framework"
 readme = "README.md"
 license = { text = "Apache-2.0" }
-version = "2.0.3"
+version = "2.0.4"
 requires-python = ">=3.11"
 keywords = [
     "csp",
@@ -100,7 +100,7 @@ Repository = "https://github.com/Point72/csp-bot"
 Homepage = "https://github.com/Point72/csp-bot"
 
 [tool.bumpversion]
-current_version = "2.0.3"
+current_version = "2.0.4"
 commit = true
 tag = true
 commit_args = "-s"

csp_bot-2.0.3/csp_bot/tests/test_help_command.py

@@ -1,63 +0,0 @@
-"""Tests for help command rendering."""
-
-from types import SimpleNamespace
-
-from chatom import Message, User
-
-from csp_bot.commands.help import HelpCommand
-from csp_bot.structs import BotCommand, CommandVariant
-
-
-def _command(backend: str) -> BotCommand:
-    return BotCommand(
-        command="help",
-        args=(),
-        source=User(id="user1"),
-        targets=(),
-        channel_id="channel1",
-        channel_name="general",
-        backend=backend,
-        variant=CommandVariant.REPLY,
-        message=Message(id="msg1", content="!help"),
-        delay=None,
-        schedule="",
-        times_run=0,
-    )
-
-
-def _commands():
-    return {
-        "ask": SimpleNamespace(name="Ask", help="Ask <anything> & get an answer", backends=[]),
-        "help": SimpleNamespace(name="Help", help="Get help with bot commands", backends=[]),
-    }
-
-
-def test_help_discord_uses_list_not_markdown_table() -> None:
-    result = HelpCommand().execute(_command("discord"), _commands())
-
-    assert result.content.startswith("**Bot Commands Help**")
-    assert "- `/ask` **Ask**: Ask <anything> & get an answer" in result.content
-    assert "| Command" not in result.content
-
-
-def test_help_slack_uses_list_not_code_block_table() -> None:
-    result = HelpCommand().execute(_command("slack"), _commands())
-
-    assert result.content.startswith("*Bot Commands Help*")
-    assert "- `/ask` *Ask*: Ask <anything> & get an answer" in result.content
-    assert "```" not in result.content
-
-
-def test_help_telegram_uses_supported_html_list() -> None:
-    result = HelpCommand().execute(_command("telegram"), _commands())
-
-    assert result.content.startswith("<b>Bot Commands Help</b>")
-    assert "- <code>/ask</code> <b>Ask</b>: Ask &lt;anything&gt; &amp; get an answer" in result.content
-    assert "<table>" not in result.content
-
-
-def test_help_symphony_keeps_table_rendering() -> None:
-    result = HelpCommand().execute(_command("symphony"), _commands())
-
-    assert "<h3>Bot Commands Help</h3>" in result.content
-    assert "<table>" in result.content