Merge pull request #1 from Burhan-Q/reorder-args

v0.2.0 -- Adds Pydantic-AI integration

Author: Burhan-Q

.gitignore

@@ -16,3 +16,6 @@ wheels/
 MacOS
 .DS_Store
 Thumbs.db
+
+.*_docs/
+.coverage

examples/01-simple_quarterly_review.py

@@ -53,7 +53,7 @@ def calculate_growth_rate(current: float, previous: float) -> dict[str, str]:
     """Calculate simple growth rate."""
     if previous == 0:
         return {"growth_rate": "N/A", "trend": "new"}
-    
+
     rate = (current - previous) / previous
     trend = "up" if rate > 0 else "down"
     return {"growth_rate": f"{rate:.1%}", "trend": trend}
@@ -104,7 +104,7 @@ def formatter(self) -> str:
         # Format with proper indentation
         data = "\n\n".join(formatted_data)
         data = indent(data, INDENT_12)
-        
+
         tools_desc = ", ".join(tool.tool_name for tool in self.tools)
         tools_desc = indent(tools_desc, INDENT_12)
 
@@ -165,7 +165,7 @@ def render(self) -> str:
 
 def main():
     """Demonstrate the simple quarterly review."""
-    
+
     print("🚀 Simple Quarterly Review Example")
     print("=" * 35)
 
@@ -188,4 +188,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

examples/04-pydantic_ai_tools_integration.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+Pydantic-AI Tools Integration Example
+
+This example demonstrates how to use pydantic-ai Tool and FunctionToolset objects
+with proompt's PromptSection. It shows:
+- Creating pydantic-ai Tool objects
+- Creating a FunctionToolset
+- Mixing ToolContext and pydantic-ai tools
+- Using tools in a PromptSection
+"""
+
+from textwrap import dedent, indent
+
+from pydantic_ai import FunctionToolset, RunContext, Tool
+
+from proompt.base.context import ToolContext
+from proompt.base.prompt import BasePrompt, PromptSection
+
+# ===== DEFINE SOME TOOLS USING PYDANTIC-AI =====
+
+
+def search_documents(query: str, max_results: int = 5) -> str:
+    """Search through company documents."""
+    return f"Found {max_results} documents matching '{query}'"
+
+
+def get_company_metrics(metric_type: str) -> dict:
+    """Retrieve company metrics."""
+    return {"revenue": 1000000, "users": 50000, "growth": 0.15}
+
+
+def calculate_percentage(numerator: float, denominator: float) -> float:
+    """Calculate percentage from two numbers."""
+    if denominator == 0:
+        return 0.0
+    return (numerator / denominator) * 100
+
+
+# Create pydantic-ai Tool objects
+search_tool = Tool(search_documents, takes_ctx=False)
+metrics_tool = Tool(get_company_metrics, takes_ctx=False)
+calc_tool = Tool(calculate_percentage, takes_ctx=False)
+
+# Create a FunctionToolset
+analysis_toolset = FunctionToolset(tools=[search_tool, metrics_tool])
+
+
+# You can also add tools using the decorator
+@analysis_toolset.tool
+def summarize_data(ctx: RunContext, data: str) -> str:
+    """Summarize the provided data."""
+    return f"Summary of {len(data)} characters of data"
+
+
+# ===== DEFINE A TRADITIONAL PROOMPT TOOL =====
+
+
+def format_report(data: dict) -> str:
+    """Format data into a readable report."""
+    return "\n".join(f"{k}: {v}" for k, v in data.items())
+
+
+proompt_tool = ToolContext(format_report)
+
+
+# ===== CREATE A PROMPT SECTION WITH MIXED TOOLS =====
+
+
+class AnalysisSection(PromptSection):
+    """A section that uses both proompt and pydantic-ai tools."""
+
+    def formatter(self) -> str:
+        tools_list = "\n" + "\n".join(f"- {tool.tool_name}: {tool.tool_description}" for tool in self.tools)
+        return dedent(f"""\
+            ## ANALYSIS TOOLS
+            
+            You have access to the following tools:
+            {indent(tools_list, " " * 12)}
+            
+            Use these tools to gather and analyze data for your report.
+            """).strip()
+
+    def render(self) -> str:
+        return self.formatter()
+
+
+# ===== CREATE THE PROMPT =====
+
+
+class MixedToolsPrompt(BasePrompt):
+    """Example prompt using both proompt and pydantic-ai tools."""
+
+    def render(self) -> str:
+        return "\n\n".join(section.render() for section in self.sections)
+
+
+# ===== DEMONSTRATE THE INTEGRATION =====
+
+
+def main():
+    print("=" * 80)
+    print("Pydantic-AI Tools Integration Demo")
+    print("=" * 80)
+    print()
+
+    # Method 1: Pass individual pydantic-ai Tool objects
+    print("Method 1: Individual Tool objects")
+    print("-" * 80)
+    section1 = AnalysisSection(tools=[search_tool, metrics_tool, calc_tool])
+    print(f"Tools in section: {len(section1.tools)}")
+    print()
+
+    # Method 2: Pass a FunctionToolset (tools are extracted automatically)
+    print("Method 2: FunctionToolset")
+    print("-" * 80)
+    section2 = AnalysisSection(tools=[analysis_toolset])
+    print(f"Tools in section: {len(section2.tools)}")
+    print("Tool names:", [t.tool_name for t in section2.tools])
+    print()
+
+    # Method 3: Mix ToolContext and pydantic-ai tools
+    print("Method 3: Mixed tools (ToolContext + pydantic-ai Tool + FunctionToolset)")
+    print("-" * 80)
+    section3 = AnalysisSection(
+        tools=[
+            proompt_tool,  # Traditional proompt tool
+            calc_tool,  # Individual pydantic-ai Tool
+            analysis_toolset,  # FunctionToolset (extracts multiple tools)
+        ]
+    )
+    print(f"Tools in section: {len(section3.tools)}")
+    print("Tool names:", [t.tool_name for t in section3.tools])
+    print()
+
+    # Create a full prompt
+    print("Full Prompt Output:")
+    print("=" * 80)
+    prompt = MixedToolsPrompt(section3)
+    print(prompt.render())
+    print()
+
+    # Demonstrate add_tools method
+    print("Using add_tools method:")
+    print("-" * 80)
+    section4 = AnalysisSection()
+    print(f"Initial tools: {len(section4.tools)}")
+
+    section4.add_tools(proompt_tool)
+    print(f"After adding ToolContext: {len(section4.tools)}")
+
+    section4.add_tools(search_tool, metrics_tool)
+    print(f"After adding pydantic-ai Tools: {len(section4.tools)}")
+
+    section4.add_tools(analysis_toolset)
+    print(f"After adding FunctionToolset: {len(section4.tools)}")
+
+    print("Final tool names:", [t.tool_name for t in section4.tools])
+    print()
+
+    # Show tool rendering
+    print("Individual Tool Rendering:")
+    print("=" * 80)
+    for tool in section3.tools[:3]:  # Show first 3 tools
+        print(f"\n{tool.tool_name}:")
+        print("-" * 40)
+        print(tool)  # automatically uses __str__() to render
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proompt"
-version = "0.1.1"
+version = "0.2.0"
 description = "Object-oriented prompting for Python"
 authors = [
     {name = "Burhan Qaddoumi"}
@@ -27,20 +27,24 @@ keywords = [
 ]
 dependencies = [
     "pydantic>=2.11.9",
+    "pydantic-ai-slim>=1.11.0",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pylint>=3.3.8",
     "pytest>=8.4.2",
     "ruff>=0.13.2",
+    "pytest-cov",
 ]
 
 [project.urls]
 homepage="https://github.com/Burhan-Q/proompt"
 source="https://github.com/Burhan-Q/proompt"
 issues="https://github.com/Burhan-Q/proompt/issues"
 
+[tool.uv]
+package=true
 
 [tool.ruff]
 # Exclude a variety of commonly ignored directories.

src/proompt/base/context.py

@@ -3,6 +3,9 @@
 from textwrap import dedent
 from typing import Callable
 
+from pydantic_ai.tools import Tool
+from pydantic_ai.toolsets import FunctionToolset
+
 
 class Context(ABC):
     """
@@ -29,9 +32,9 @@ class ToolContext(Context):
     Attributes:
         tool_use (str): Description of how to use the tool.
         tool_name (str): Name of the tool.
+        tool_description (str): Description of the tool's functionality.
         tool_args (MappingProxytype): Arguments accepted by the tool.
         output_type (Any): Expected output type of the tool.
-        tool_description (str): Description of the tool's functionality.
 
     Methods:
         args_render: renders text for tool arguments
@@ -43,9 +46,53 @@ def __init__(self, tool: Callable, tool_use: str | None = None) -> None:
         self._tool = tool
         self.tool_use = tool_use or "Reference description for usage."
         self.tool_name = tool.__name__
+        self.tool_description = tool.__doc__ or "No description available."
         self.tool_args = inspect.signature(tool).parameters
         self.output_type = inspect.signature(tool).return_annotation
-        self.tool_description = tool.__doc__ or "No description available."
+
+    @classmethod
+    def from_pydantic_tool(cls, tool: Tool) -> "ToolContext":
+        """
+        Create a ToolContext from a pydantic-ai Tool object.
+
+        Args:
+            tool: A pydantic-ai Tool instance
+
+        Returns:
+            ToolContext wrapping the tool's function with its metadata
+        """
+        return cls(tool=tool.function)
+
+    @classmethod
+    def normalize(cls, tool: Callable | "ToolContext" | Tool | FunctionToolset | None) -> list["ToolContext"]:
+        """
+        Normalize any tool type to a list of ToolContext instances.
+
+        Accepts:
+        - ToolContext: Returns as single-item list
+        - Tool (pydantic-ai): Converts via from_pydantic_tool
+        - FunctionToolset (pydantic-ai): Extracts all tools from .tools dict
+        - None or invalid: Returns empty list
+
+        Args:
+            tool (Callable | ToolContext | Tool | FunctionToolset | None): Tool of any supported type
+
+        Returns:
+            List of ToolContext instances (may be empty)
+        """
+        result: list[ToolContext] = []
+
+        if isinstance(tool, cls):
+            result.append(tool)
+        elif isinstance(tool, Tool):
+            result.append(cls.from_pydantic_tool(tool))
+        elif isinstance(tool, FunctionToolset):
+            for pydantic_tool in tool.tools.values():
+                result.append(cls.from_pydantic_tool(pydantic_tool))
+        elif isinstance(tool, Callable):
+            result.append(cls(tool=tool))
+
+        return result
 
     def args_render(self) -> str:
         """Render the tool arguments as a string."""

src/proompt/base/prompt.py

@@ -25,12 +25,15 @@ class PromptSection(ABC):
     def __init__(
         self,
         context: Context | None = None,
-        tools: list[ToolContext] | None = None,
+        tools: list | None = None,
         *providers: BaseProvider | None,
-    ):
+    ) -> None:
+        """Initialize the PromptSection with context, tools, and providers."""
         self._context = context
         self.providers = list(providers or [])
-        self.tools = tools or []
+        self.tools: list[ToolContext] = []
+        for t in tools or []:
+            self.tools.extend(ToolContext.normalize(t))
 
     @property
     def context(self) -> Context:
@@ -50,9 +53,10 @@ def add_providers(self, *providers: BaseProvider) -> None:
         """Add variable quantity of providers."""
         self.providers.extend([p for p in providers if isinstance(p, BaseProvider)])
 
-    def add_tools(self, *tools: ToolContext) -> None:
-        """Add variable quantity of tools."""
-        self.tools.extend([t for t in tools if isinstance(t, ToolContext)])
+    def add_tools(self, *tools) -> None:
+        """Add variable quantity of tools (ToolContext, pydantic-ai Tool, or FunctionToolset)."""
+        for t in tools:
+            self.tools.extend(ToolContext.normalize(t))
 
     @abstractmethod
     def formatter(self, *args, **kwargs) -> str:
@@ -81,6 +85,7 @@ class BasePrompt(ABC):
     """
 
     def __init__(self, *sections: PromptSection) -> None:
+        """Initialize the BasePrompt with sections."""
         self.sections = list(sections or [])
 
     @abstractmethod