hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/prompts/tool_prompts.py

@@ -0,0 +1,160 @@
+"""Composable tool usage prompt templates.
+
+These prompts provide tool calling instructions that can be composed
+with other prompts using the builder pattern.
+"""
+
+from hexdag.builtin.nodes.tool_utils import ToolCallFormat
+from hexdag.core.orchestration.prompt.template import PromptTemplate
+
+
+class FunctionToolPrompt(PromptTemplate):
+    """Tool usage prompt for function-style tool calls.
+
+    Format: INVOKE_TOOL: tool_name(param='value')
+
+    This prompt is composable - add it to any base prompt:
+        main_prompt + FunctionToolPrompt()
+
+    Examples
+    --------
+    Standalone usage:
+        >>> prompt = FunctionToolPrompt()
+        >>> text = prompt.render(
+        ...     tools="search(query), calculator(expression)",
+        ...     tool_schemas=[...]
+        ... )
+
+    Composed with main prompt:
+        >>> main = PromptTemplate("Analyze {{data}}")
+        >>> full_prompt = main + FunctionToolPrompt()
+    """
+
+    def __init__(self) -> None:
+        """Initialize function-style tool prompt template."""
+        template = """
+## Available Tools
+{{tools}}
+
+## Usage Guidelines
+- Call ONE tool at a time using: INVOKE_TOOL: tool_name(param='value')
+- Use single quotes for string parameters
+- For final answer and structured output: INVOKE_TOOL: tool_end(field1='value1', field2='value2')
+- For phase change: INVOKE_TOOL: change_phase(phase='new_phase', reason='why changing', carried_data={'key': 'value'})
+
+## Examples
+INVOKE_TOOL: search(query='latest AI news')
+INVOKE_TOOL: calculator(expression='2 + 2')
+INVOKE_TOOL: tool_end(result='Analysis complete', confidence='high')
+"""
+        super().__init__(template, input_vars=["tools"])
+
+
+class JsonToolPrompt(PromptTemplate):
+    """Tool usage prompt for JSON-style tool calls.
+
+    Format: INVOKE_TOOL: {"tool": "tool_name", "params": {"param": "value"}}
+
+    This prompt is composable - add it to any base prompt:
+        main_prompt + JsonToolPrompt()
+
+    Examples
+    --------
+    Standalone usage:
+        >>> prompt = JsonToolPrompt()
+        >>> text = prompt.render(tools="search, calculator", tool_schemas=[...])
+
+    Composed with main prompt:
+        >>> main = PromptTemplate("Analyze {{data}}")
+        >>> full_prompt = main + JsonToolPrompt()
+    """
+
+    def __init__(self) -> None:
+        """Initialize JSON-style tool prompt template."""
+        template = """
+## Available Tools
+{{tools}}
+
+## Usage Guidelines
+- Call ONE tool at a time using JSON format
+- Format: INVOKE_TOOL: {"tool": "tool_name", "params": {"param": "value"}}
+- Use valid JSON syntax with double quotes
+- For final answer: INVOKE_TOOL: {"tool": "tool_end", "params": {"field1": "value1", "field2": "value2"}}
+- For phase change: INVOKE_TOOL: {"tool": "change_phase", "params": {"phase": "new_phase", "reason": "why", "carried_data": {"key": "val"}}}
+
+## Examples
+INVOKE_TOOL: {"tool": "search", "params": {"query": "latest AI news"}}
+INVOKE_TOOL: {"tool": "calculator", "params": {"expression": "2 + 2"}}
+INVOKE_TOOL: {"tool": "tool_end", "params": {"result": "Analysis complete", "confidence": "high"}}
+"""
+        super().__init__(template, input_vars=["tools"])
+
+
+class MixedToolPrompt(PromptTemplate):
+    """Tool usage prompt supporting both function and JSON styles.
+
+    Format: Either function or JSON style
+    - Function: INVOKE_TOOL: tool_name(param='value')
+    - JSON: INVOKE_TOOL: {"tool": "tool_name", "params": {"param": "value"}}
+
+    This prompt is composable - add it to any base prompt:
+        main_prompt + MixedToolPrompt()
+
+    Examples
+    --------
+    Standalone usage:
+        >>> prompt = MixedToolPrompt()
+        >>> text = prompt.render(tools="search, calculator", tool_schemas=[...])
+
+    Composed with main prompt:
+        >>> main = PromptTemplate("Analyze {{data}}")
+        >>> full_prompt = main + MixedToolPrompt()
+    """
+
+    def __init__(self) -> None:
+        """Initialize mixed-style tool prompt template."""
+        template = """
+## Available Tools
+{{tools}}
+
+## Usage Guidelines
+- Call ONE tool at a time using either format:
+  - Function style: INVOKE_TOOL: tool_name(param='value')
+  - JSON style: INVOKE_TOOL: {"tool": "tool_name", "params": {"param": "value"}}
+
+### Function Style Examples
+INVOKE_TOOL: search(query='latest AI news')
+INVOKE_TOOL: tool_end(result='Analysis complete', confidence='high')
+INVOKE_TOOL: change_phase(phase='refinement', reason='need more data', carried_data={'initial': 'findings'})
+
+### JSON Style Examples
+INVOKE_TOOL: {"tool": "search", "params": {"query": "latest AI news"}}
+INVOKE_TOOL: {"tool": "tool_end", "params": {"result": "Analysis complete", "confidence": "high"}}
+INVOKE_TOOL: {"tool": "change_phase", "params": {"phase": "refinement", "reason": "need more data", "carried_data": {"initial": "findings"}}}
+"""
+        super().__init__(template, input_vars=["tools"])
+
+
+def get_tool_prompt_for_format(format_style: ToolCallFormat) -> type[PromptTemplate]:
+    """Get the appropriate tool prompt class for a given format.
+
+    Args
+    ----
+        format_style: Tool call format (FUNCTION_CALL, JSON, or MIXED)
+
+    Returns
+    -------
+    type[PromptTemplate]
+        Appropriate tool prompt class
+
+    Examples
+    --------
+        >>> PromptClass = get_tool_prompt_for_format(ToolCallFormat.FUNCTION_CALL)
+        >>> prompt = PromptClass()
+        >>> text = prompt.render(tools="search, calculator")
+    """
+    if format_style == ToolCallFormat.FUNCTION_CALL:
+        return FunctionToolPrompt
+    if format_style == ToolCallFormat.JSON:
+        return JsonToolPrompt
+    return MixedToolPrompt

hexdag/builtin/tools/builtin_tools.py

@@ -0,0 +1,84 @@
+"""Built-in tools that are essential for agent operations."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hexdag.builtin.nodes.agent_node import PhaseContext
+
+
+def tool_end(**kwargs: Any) -> dict[str, Any]:
+    """End tool execution with structured output.
+
+    This is a built-in tool that agents can use to return
+    structured data matching their output schema.
+
+    Args
+    ----
+        **kwargs: Any structured data to return
+
+    Returns
+    -------
+        The structured data as provided
+    """
+    return kwargs
+
+
+def change_phase(
+    phase: str,
+    previous_phase: str | None = None,
+    reason: str | None = None,
+    carried_data: dict[str, Any] | None = None,
+    target_output: str | None = None,
+    iteration: int | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Change the agent's reasoning phase with typed context.
+
+    This tool allows agents to transition between different
+    reasoning phases with strongly-typed context data.
+
+    Args
+    ----
+        phase: The new phase name to transition to
+        previous_phase: The phase being transitioned from (auto-filled if not provided)
+        reason: Explanation for why the phase change is occurring
+        carried_data: Data to carry forward from the previous phase
+        target_output: Expected output format or goal for the new phase
+        iteration: Current iteration number if in a loop or retry scenario
+        metadata: Additional metadata about the phase transition
+
+    Returns
+    -------
+        Dictionary with phase change information including:
+        - action: Always "change_phase"
+        - new_phase: The phase being transitioned to
+        - context: PhaseContext-typed data
+
+    Examples
+    --------
+    >>> change_phase("analysis", reason="Initial data gathering complete")
+    {'action': 'change_phase', 'new_phase': 'analysis', 'context': {'reason':
+    'Initial data gathering complete'}}
+
+    >>> change_phase("synthesis",
+    ...              previous_phase="analysis",
+    ...              carried_data={"key_findings": ["item1", "item2"]},
+    ...              iteration=2)
+    {'action': 'change_phase', 'new_phase': 'synthesis', 'context': {...}}
+    """
+    context: PhaseContext = {}
+
+    if previous_phase is not None:
+        context["previous_phase"] = previous_phase
+    if reason is not None:
+        context["reason"] = reason
+    if carried_data is not None:
+        context["carried_data"] = carried_data
+    if target_output is not None:
+        context["target_output"] = target_output
+    if iteration is not None:
+        context["iteration"] = iteration
+    if metadata is not None:
+        context["metadata"] = metadata
+
+    return {"action": "change_phase", "new_phase": phase, "context": context}

hexdag/builtin/tools/database_tools.py

@@ -0,0 +1,164 @@
+"""Database-related tools that require database port."""
+
+import asyncio
+from typing import Any
+
+from hexdag.core.exceptions import DependencyError
+from hexdag.core.ports.database import DatabasePort
+
+
+async def database_query(
+    sql: str, params: dict[str, Any] | None = None, database_port: DatabasePort | None = None
+) -> list[dict[str, Any]]:
+    """Execute a SQL query on the database.
+
+    This tool requires a database port to be available.
+    The database port will be injected when the tool is executed.
+
+    Args
+    ----
+        sql: SQL query to execute
+        params: Optional parameters for parameterized queries
+        database_port: Injected database port (provided by framework)
+
+    Returns
+    -------
+        List of dictionaries representing query results
+
+    Raises
+    ------
+    DependencyError
+        If database port is not provided
+    """
+    if database_port is None:
+        raise DependencyError("database_port", "required for database query execution")
+
+    # Use the database port to execute the query
+    return await database_port.aexecute_query(sql, params or {})
+
+
+async def database_execute(
+    sql: str, params: dict[str, Any] | None = None, database_port: Any | None = None
+) -> None:
+    """Execute a SQL command (INSERT, UPDATE, DELETE) on the database.
+
+    This tool requires a database port to be available.
+
+    Args
+    ----
+        sql: SQL command to execute
+        params: Optional parameters for parameterized queries
+        database_port: Injected database port (provided by framework)
+
+    Raises
+    ------
+    DependencyError
+        If database port is not provided
+    """
+    if database_port is None:
+        raise DependencyError("database_port", "required for database query execution")
+
+    # Execute returns no value, just runs the query
+    await database_port.aexecute_query(sql, params or {})
+
+
+async def list_tables(database_port: DatabasePort | None = None) -> list[str]:
+    """List all tables in the database.
+
+    Args
+    ----
+        database_port: Injected database port
+
+    Returns
+    -------
+        List of table names
+
+    Raises
+    ------
+    DependencyError
+        If database port is not provided
+    """
+    if database_port is None:
+        raise DependencyError("database_port", "required for database query execution")
+
+    # Standard SQL to get table list (may vary by database)
+    sql = """
+    SELECT table_name
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+    """
+
+    results = await database_port.aexecute_query(sql)
+    return [row["table_name"] for row in results]
+
+
+async def describe_table(
+    table: str, database_port: DatabasePort | None = None
+) -> list[dict[str, Any]]:
+    """Get schema information for a database table.
+
+    Args
+    ----
+        table: Name of the table
+        database_port: Injected database port
+
+    Returns
+    -------
+        List of column information
+
+    Raises
+    ------
+    DependencyError
+        If database port is not provided
+    """
+    if database_port is None:
+        raise DependencyError("database_port", "required for database query execution")
+
+    sql = """
+    SELECT
+        column_name,
+        data_type,
+        is_nullable,
+        column_default
+    FROM information_schema.columns
+    WHERE table_name = :table
+    ORDER BY ordinal_position
+    """
+
+    return await database_port.aexecute_query(sql, {"table": table})
+
+
+# Synchronous versions for compatibility
+def database_query_sync(
+    sql: str, params: dict[str, Any] | None = None, database_port: DatabasePort | None = None
+) -> list[dict[str, Any]]:
+    """Execute a database query synchronously.
+
+    Args
+    ----
+        sql: SQL query to execute
+        params: Optional parameters
+        database_port: Injected database port
+
+    Returns
+    -------
+        Query results
+
+    Raises
+    ------
+    DependencyError
+        If database port is not provided
+    """
+    if database_port is None:
+        raise DependencyError("database_port", "required for database query execution")
+    return asyncio.run(database_port.aexecute_query(sql, params or {}))
+
+
+# Export key tools
+__all__ = [
+    "database_query",
+    "database_execute",
+    "list_tables",
+    "describe_table",
+    "database_query_sync",
+]

hexdag/cli/__init__.py

@@ -0,0 +1,17 @@
+"""Command-line interface for HexDAG.
+
+Note: The CLI requires the 'cli' extra to be installed:
+    pip install hexdag[cli]
+    or
+    uv pip install hexdag[cli]
+"""
+
+
+def main() -> None:
+    """Entry point for HexDAG CLI."""
+    from hexdag.cli.main import main as cli_main
+
+    return cli_main()
+
+
+__all__ = ["main"]

hexdag/cli/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Entry point for HexDAG CLI when run as python -m hexdag.cli."""
+
+if __name__ == "__main__":
+    from hexdag.cli.main import main
+
+    main()

hexdag/cli/commands/__init__.py

@@ -0,0 +1,27 @@
+"""CLI command modules."""
+
+from . import (
+    build_cmd,
+    create_cmd,
+    docs_cmd,
+    generate_types_cmd,
+    init_cmd,
+    pipeline_cmd,
+    plugin_dev_cmd,
+    plugins_cmd,
+    studio_cmd,
+    validate_cmd,
+)
+
+__all__ = [
+    "build_cmd",
+    "create_cmd",
+    "docs_cmd",
+    "generate_types_cmd",
+    "init_cmd",
+    "pipeline_cmd",
+    "plugin_dev_cmd",
+    "plugins_cmd",
+    "studio_cmd",
+    "validate_cmd",
+]