agentpool 2.1.9__py3-none-any.whl

agentpool_config/hook_conditions.py

@@ -0,0 +1,331 @@
+"""Condition models for hook filtering."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import ConfigDict, Field
+from schemez import Schema
+
+
+class BaseHookCondition(Schema):
+    """Base class for hook conditions."""
+
+    type: str = Field(init=False, title="Condition type")
+    """Discriminator for condition types."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+# === Tool Hook Conditions ===
+
+
+class ToolNameCondition(BaseHookCondition):
+    """Match tool by name pattern."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Tool Name Condition"})
+
+    type: Literal["tool_name"] = Field("tool_name", init=False)
+    """Tool name pattern condition."""
+
+    pattern: str = Field(
+        examples=["Bash", "Write|Edit", "mcp__.*", ".*"],
+        title="Name pattern",
+    )
+    """Regex pattern to match tool names."""
+
+
+class ArgumentCondition(BaseHookCondition):
+    """Check tool argument values."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Argument Condition"})
+
+    type: Literal["argument"] = Field("argument", init=False)
+    """Argument value condition."""
+
+    key: str = Field(
+        examples=["command", "file_path", "options.force"],
+        title="Argument key",
+    )
+    """Argument name to check. Supports dot notation for nested access."""
+
+    pattern: str | None = Field(
+        default=None,
+        examples=["rm\\s+-rf", "^/tmp/.*", ".*\\.py$"],
+        title="Regex pattern",
+    )
+    """Regex pattern to match argument value."""
+
+    contains: str | None = Field(
+        default=None,
+        examples=["sudo", "DROP TABLE", "../"],
+        title="Substring match",
+    )
+    """Substring that must be present in argument value."""
+
+    equals: Any | None = Field(
+        default=None,
+        examples=[True, "/etc/passwd", 0],
+        title="Exact value",
+    )
+    """Exact value the argument must equal."""
+
+    case_sensitive: bool = Field(default=True, title="Case sensitive")
+    """Whether string matching is case-sensitive."""
+
+
+class ArgumentExistsCondition(BaseHookCondition):
+    """Check if an argument is present."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Argument Exists Condition"})
+
+    type: Literal["argument_exists"] = Field("argument_exists", init=False)
+    """Argument existence condition."""
+
+    key: str = Field(
+        examples=["force", "recursive", "timeout"],
+        title="Argument key",
+    )
+    """Argument name that must exist (or not exist)."""
+
+    exists: bool = Field(default=True, title="Must exist")
+    """If True, argument must exist. If False, argument must not exist."""
+
+
+class Jinja2HookCondition(BaseHookCondition):
+    """Flexible Jinja2 template condition for hooks."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Jinja2 Hook Condition"})
+
+    type: Literal["jinja2"] = Field("jinja2", init=False)
+    """Jinja2 template condition."""
+
+    template: str = Field(
+        examples=[
+            "{{ tool_name == 'Bash' and 'sudo' in tool_input.get('command', '') }}",
+            "{{ tool_input.get('path', '').startswith('/tmp') }}",
+            "{{ 'password' in tool_input | string | lower }}",
+        ],
+        title="Jinja2 template",
+    )
+    """Jinja2 template that evaluates to true/false.
+
+    Available variables depend on hook event:
+    - tool_name: Name of the tool (tool hooks)
+    - tool_input: Tool arguments dict (tool hooks)
+    - tool_output: Tool result (post_tool_use only)
+    - duration_ms: Execution time in ms (post_tool_use only)
+    - prompt: User prompt (run hooks)
+    - result: Run result (post_run only)
+    - agent_name: Name of the agent
+    - event: Hook event name
+    """
+
+
+class DurationCondition(BaseHookCondition):
+    """Check tool execution duration (post_tool_use only)."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Duration Condition"})
+
+    type: Literal["duration"] = Field("duration", init=False)
+    """Duration threshold condition."""
+
+    min_ms: float | None = Field(
+        default=None,
+        ge=0,
+        examples=[1000, 5000],
+        title="Minimum duration (ms)",
+    )
+    """Minimum duration in milliseconds. Triggers if duration >= min_ms."""
+
+    max_ms: float | None = Field(
+        default=None,
+        ge=0,
+        examples=[100, 500],
+        title="Maximum duration (ms)",
+    )
+    """Maximum duration in milliseconds. Triggers if duration <= max_ms."""
+
+
+class OutputCondition(BaseHookCondition):
+    """Check tool output content (post_tool_use only)."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Output Condition"})
+
+    type: Literal["output"] = Field("output", init=False)
+    """Output content condition."""
+
+    pattern: str | None = Field(
+        default=None,
+        examples=["error", "Exception", "failed"],
+        title="Regex pattern",
+    )
+    """Regex pattern to match in output."""
+
+    contains: str | None = Field(
+        default=None,
+        examples=["success", "error", "warning"],
+        title="Substring match",
+    )
+    """Substring that must be present in output."""
+
+    case_sensitive: bool = Field(default=False, title="Case sensitive")
+    """Whether string matching is case-sensitive."""
+
+
+class OutputSizeCondition(BaseHookCondition):
+    """Check tool output size (post_tool_use only)."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Output Size Condition"})
+
+    type: Literal["output_size"] = Field("output_size", init=False)
+    """Output size condition."""
+
+    min_chars: int | None = Field(
+        default=None,
+        ge=0,
+        examples=[1000, 10000],
+        title="Minimum size",
+    )
+    """Minimum output length in characters."""
+
+    max_chars: int | None = Field(
+        default=None,
+        ge=0,
+        examples=[100, 500],
+        title="Maximum size",
+    )
+    """Maximum output length in characters."""
+
+
+# === Run Hook Conditions ===
+
+
+class PromptCondition(BaseHookCondition):
+    """Check prompt content (pre_run/post_run)."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "Prompt Condition"})
+
+    type: Literal["prompt"] = Field("prompt", init=False)
+    """Prompt content condition."""
+
+    pattern: str | None = Field(
+        default=None,
+        examples=["^(help|\\?)$", ".*password.*"],
+        title="Regex pattern",
+    )
+    """Regex pattern to match in prompt."""
+
+    contains: str | None = Field(
+        default=None,
+        examples=["delete", "remove all"],
+        title="Substring match",
+    )
+    """Substring that must be present in prompt."""
+
+    case_sensitive: bool = Field(default=False, title="Case sensitive")
+    """Whether string matching is case-sensitive."""
+
+
+# === Combinators ===
+
+
+class AndHookCondition(BaseHookCondition):
+    """Require all conditions to be met."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "AND Hook Condition"})
+
+    type: Literal["and"] = Field("and", init=False)
+    """AND combinator for conditions."""
+
+    conditions: list[HookCondition] = Field(
+        min_length=1,
+        title="Conditions",
+    )
+    """All conditions must be true."""
+
+
+class OrHookCondition(BaseHookCondition):
+    """Require any condition to be met."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "OR Hook Condition"})
+
+    type: Literal["or"] = Field("or", init=False)
+    """OR combinator for conditions."""
+
+    conditions: list[HookCondition] = Field(
+        min_length=1,
+        title="Conditions",
+    )
+    """At least one condition must be true."""
+
+
+class NotHookCondition(BaseHookCondition):
+    """Negate a condition."""
+
+    model_config = ConfigDict(json_schema_extra={"title": "NOT Hook Condition"})
+
+    type: Literal["not"] = Field("not", init=False)
+    """NOT combinator for conditions."""
+
+    condition: HookCondition = Field(title="Condition")
+    """Condition to negate."""
+
+
+# === Union Types ===
+
+
+# Conditions valid for pre_tool_use
+PreToolCondition = Annotated[
+    ToolNameCondition
+    | ArgumentCondition
+    | ArgumentExistsCondition
+    | Jinja2HookCondition
+    | AndHookCondition
+    | OrHookCondition
+    | NotHookCondition,
+    Field(discriminator="type"),
+]
+
+# Conditions valid for post_tool_use (includes duration/output checks)
+PostToolCondition = Annotated[
+    ToolNameCondition
+    | ArgumentCondition
+    | ArgumentExistsCondition
+    | Jinja2HookCondition
+    | DurationCondition
+    | OutputCondition
+    | OutputSizeCondition
+    | AndHookCondition
+    | OrHookCondition
+    | NotHookCondition,
+    Field(discriminator="type"),
+]
+
+# Conditions valid for pre_run/post_run
+RunCondition = Annotated[
+    PromptCondition | Jinja2HookCondition | AndHookCondition | OrHookCondition | NotHookCondition,
+    Field(discriminator="type"),
+]
+
+# General hook condition (all types)
+HookCondition = Annotated[
+    ToolNameCondition
+    | ArgumentCondition
+    | ArgumentExistsCondition
+    | Jinja2HookCondition
+    | DurationCondition
+    | OutputCondition
+    | OutputSizeCondition
+    | PromptCondition
+    | AndHookCondition
+    | OrHookCondition
+    | NotHookCondition,
+    Field(discriminator="type"),
+]
+
+
+# Update forward references for recursive types
+AndHookCondition.model_rebuild()
+OrHookCondition.model_rebuild()
+NotHookCondition.model_rebuild()

agentpool_config/hooks.py

@@ -0,0 +1,241 @@
+"""Hook configuration models for agent lifecycle events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any, Literal
+
+from pydantic import ConfigDict, Field
+from schemez import Schema
+
+
+if TYPE_CHECKING:
+    from agentpool.hooks.base import Hook, HookEvent
+
+
+class BaseHookConfig(Schema):
+    """Base configuration for hooks."""
+
+    type: str = Field(init=False, title="Hook type")
+    """Hook type discriminator."""
+
+    matcher: str | None = Field(
+        default=None,
+        examples=["Write|Edit", "Bash.*", "*"],
+        title="Pattern matcher",
+    )
+    """Regex pattern to match tool names. None or '*' matches all."""
+
+    timeout: float = Field(
+        default=60.0,
+        gt=0,
+        examples=[30.0, 60.0, 120.0],
+        title="Timeout seconds",
+    )
+    """Maximum execution time in seconds."""
+
+    enabled: bool = Field(default=True, title="Hook enabled")
+    """Whether this hook is active."""
+
+    def get_hook(self, event: HookEvent) -> Hook:
+        """Create runtime hook from this config.
+
+        Args:
+            event: The lifecycle event this hook handles.
+
+        Returns:
+            Runtime hook instance.
+        """
+        raise NotImplementedError
+
+
+class CommandHookConfig(BaseHookConfig):
+    """Hook that executes a shell command.
+
+    The command receives hook input as JSON via stdin and should return
+    JSON output via stdout. Exit code 0 = success, exit code 2 = block.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Command Hook"})
+
+    type: Literal["command"] = Field("command", init=False)
+    """Command hook type."""
+
+    command: str = Field(
+        examples=[
+            "/path/to/script.sh",
+            "$PROJECT_DIR/hooks/validate.py",
+            "python -m myproject.hooks.check",
+        ],
+        title="Shell command",
+    )
+    """Shell command to execute. Supports $PROJECT_DIR variable."""
+
+    env: dict[str, str] | None = Field(
+        default=None,
+        examples=[{"DEBUG": "1", "LOG_LEVEL": "info"}],
+        title="Environment variables",
+    )
+    """Additional environment variables for the command."""
+
+    def get_hook(self, event: HookEvent) -> Hook:
+        """Create runtime command hook."""
+        from agentpool.hooks import CommandHook
+
+        return CommandHook(
+            event=event,
+            command=self.command,
+            matcher=self.matcher,
+            timeout=self.timeout,
+            enabled=self.enabled,
+            env=self.env,
+        )
+
+
+class CallableHookConfig(BaseHookConfig):
+    """Hook that executes a Python callable.
+
+    The callable receives hook input as a dictionary and should return
+    a HookResult dictionary or None.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Callable Hook"})
+
+    type: Literal["callable"] = Field("callable", init=False)
+    """Callable hook type."""
+
+    import_path: str = Field(
+        examples=[
+            "myproject.hooks.validate_tool",
+            "myapp.security.audit_command",
+        ],
+        title="Import path",
+    )
+    """Dotted import path to the callable."""
+
+    arguments: dict[str, Any] = Field(
+        default_factory=dict,
+        examples=[{"strict": True, "allowed_paths": ["/tmp"]}],
+        title="Arguments",
+    )
+    """Additional keyword arguments passed to the callable."""
+
+    def get_hook(self, event: HookEvent) -> Hook:
+        """Create runtime callable hook."""
+        from agentpool.hooks import CallableHook
+
+        return CallableHook(
+            event=event,
+            fn=self.import_path,
+            matcher=self.matcher,
+            timeout=self.timeout,
+            enabled=self.enabled,
+            arguments=self.arguments,
+        )
+
+
+class PromptHookConfig(BaseHookConfig):
+    """Hook that uses an LLM to evaluate the action.
+
+    The prompt is sent to a fast LLM which returns a structured decision.
+    Use $TOOL_NAME, $TOOL_INPUT, $INPUT placeholders in the prompt.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Prompt Hook"})
+
+    type: Literal["prompt"] = Field("prompt", init=False)
+    """Prompt-based hook type."""
+
+    prompt: str = Field(
+        examples=[
+            "Evaluate if this tool call is safe: $INPUT",
+            "Check if $TOOL_NAME with input $TOOL_INPUT follows security policies.",
+        ],
+        title="Evaluation prompt",
+    )
+    """Prompt template for LLM evaluation. Supports placeholders."""
+
+    model: str | None = Field(
+        default=None,
+        examples=["openai:gpt-4o-mini", "google-gla:gemini-2.0-flash"],
+        title="Model",
+    )
+    """Model to use for evaluation. Defaults to a fast model if not specified."""
+
+    def get_hook(self, event: HookEvent) -> Hook:
+        """Create runtime prompt hook."""
+        from agentpool.hooks import PromptHook
+
+        return PromptHook(
+            event=event,
+            prompt=self.prompt,
+            matcher=self.matcher,
+            timeout=self.timeout,
+            enabled=self.enabled,
+            model=self.model,
+        )
+
+
+HookConfig = Annotated[
+    CommandHookConfig | CallableHookConfig | PromptHookConfig,
+    Field(discriminator="type"),
+]
+"""Union of all hook configuration types."""
+
+
+class HooksConfig(Schema):
+    """Configuration for agent lifecycle hooks.
+
+    Hooks allow intercepting and customizing agent behavior at key points
+    in the execution lifecycle. They can add context, block operations,
+    modify inputs, or trigger side effects.
+
+    Currently supported events:
+    - pre_run / post_run: Before/after agent.run() processes a prompt
+    - pre_tool_use / post_tool_use: Before/after a tool is called
+    """
+
+    # Message flow events
+    pre_run: list[HookConfig] = Field(
+        default_factory=list,
+        title="Pre-run hooks",
+    )
+    """Hooks executed before agent.run() processes a prompt."""
+
+    post_run: list[HookConfig] = Field(
+        default_factory=list,
+        title="Post-run hooks",
+    )
+    """Hooks executed after agent.run() completes."""
+
+    # Tool execution events
+    pre_tool_use: list[HookConfig] = Field(
+        default_factory=list,
+        title="Pre-tool-use hooks",
+    )
+    """Hooks executed before a tool is called. Can block or modify the call."""
+
+    post_tool_use: list[HookConfig] = Field(
+        default_factory=list,
+        title="Post-tool-use hooks",
+    )
+    """Hooks executed after a tool completes."""
+
+    def get_agent_hooks(self) -> AgentHooks:
+        """Create runtime AgentHooks from this configuration.
+
+        Returns:
+            AgentHooks instance with all hooks instantiated.
+        """
+        from agentpool.hooks import AgentHooks
+
+        return AgentHooks(
+            pre_run=[cfg.get_hook("pre_run") for cfg in self.pre_run],
+            post_run=[cfg.get_hook("post_run") for cfg in self.post_run],
+            pre_tool_use=[cfg.get_hook("pre_tool_use") for cfg in self.pre_tool_use],
+            post_tool_use=[cfg.get_hook("post_tool_use") for cfg in self.post_tool_use],
+        )
+
+
+# Import for type checking only - avoid circular imports
+if TYPE_CHECKING:
+    from agentpool.hooks import AgentHooks