Publishing Tools from Your App

@agent_tool
def get_customer_orders(customer_id: str):
    """
    Retrieve all sales orders for a customer with order details,
    status, and totals. Use this when users ask about customer
    order history or purchase patterns.
    """
    pass

@agent_tool
def create_quote(items: list, customer_id: str, valid_until: str = None):
    """
    Create a sales quote with items for a customer.
    
    Args:
        items (list): List of items with 'item_code', 'qty', 'rate'
        customer_id (str): Customer ID to quote for
        valid_until (str, optional): Quote expiry date (YYYY-MM-DD)
        
    Returns:
        dict: Created quote details with quote ID
    """
    pass

@agent_tool
def analyze_sales_trends(period_days: int = 30):
    """
    Analyze sales trends over a period.
    
    Returns:
        dict: Analysis results with:
            - total_revenue (float): Total sales in period
            - order_count (int): Number of orders
            - top_customers (list): Top 5 customers by revenue
            - growth_rate (float): Percentage growth vs previous period
    """
    pass

# Pricing tools
@agent_tool(category="Pricing")
def calculate_discount(...):
    pass
 
@agent_tool(category="Pricing")
def apply_promotion_code(...):
    pass
 
# Inventory tools
@agent_tool(category="Inventory")
def check_stock_levels(...):
    pass
 
@agent_tool(category="Inventory")
def calculate_reorder_quantity(...):
    pass

import frappe
 
@agent_tool
def advanced_analytics(...):
    """Advanced analytics (requires Analytics app)."""
    if not frappe.db.exists("Module Def", {"name": "Analytics"}):
        frappe.throw("Analytics module not installed")
    # Implementation
    pass

@agent_tool
def sync_with_external_system(...):
    """
    Sync data with external system.
    
    Requires:
        - External API credentials configured
        - Network access to external system
        - Valid API key in app settings
    """
    pass

@agent_tool
def old_tool_name(...):
    """DEPRECATED: Use new_tool_name instead."""
    frappe.msgprint("This tool is deprecated. Use new_tool_name.")
    return new_tool_name(...)
 
@agent_tool
def new_tool_name(...):
    """Improved version of old tool."""
    pass

@agent_tool
def tool_name(param1, param2=None, **kwargs):
    """Handle both old and new parameter formats."""
    # Support old format
    if param2 is None and 'old_param' in kwargs:
        param2 = kwargs['old_param']
    # New implementation
    pass

@agent_tool
def process_order(order_id: str, payment_method: str) -> dict:
    """
    Process a sales order with payment and inventory updates.
    
    This tool handles the complete order processing workflow including
    payment validation, inventory deduction, and order confirmation.
    
    Args:
        order_id (str): The sales order ID to process
        payment_method (str): Payment method (Card, Bank Transfer, Cash)
        
    Returns:
        dict: Processing result with:
            - success (bool): Whether processing succeeded
            - invoice_id (str): Generated invoice ID if successful
            - errors (list): Any errors encountered
            
    Raises:
        frappe.ValidationError: If order is invalid or cannot be processed
        
    Example:
        >>> process_order("SO-2024-001", "Card")
        {"success": True, "invoice_id": "INV-2024-001", "errors": []}
        
    Note:
        This tool requires:
        - Order must be in Draft status
        - Sufficient inventory available
        - Valid payment method configured
    """
    pass

@agent_tool
def safe_operation(param: str) -> dict:
    """Safe operation with error handling."""
    try:
        # Validate input
        if not param:
            frappe.throw("Parameter is required")
        
        # Perform operation
        result = perform_operation(param)
        
        return {"success": True, "result": result}
        
    except frappe.ValidationError as e:
        # User errors - return to agent
        return {"success": False, "error": str(e)}
        
    except Exception as e:
        # System errors - log and return generic message
        frappe.log_error(f"Tool error: {str(e)}")
        return {"success": False, "error": "An error occurred processing your request"}

# In your app's test file
import unittest
 
class TestTools(unittest.TestCase):
    def test_calculate_discount(self):
        from my_app.api.tools import calculate_discount
        
        result = calculate_discount("Wholesale", 1000.0)
        
        self.assertEqual(result["discount_pct"], 15.0)
        self.assertEqual(result["discount_amount"], 150.0)
        self.assertEqual(result["final_total"], 850.0)

"""
Agent tools for My App.
 
This module provides reusable tools for Huf agents.
"""
 
import frappe
from huf.ai.tool_discovery import agent_tool
from typing import List, Dict, Optional
 
@agent_tool(category="Sales")
def get_customer_orders(customer_id: str, status: Optional[str] = None) -> Dict:
    """
    Retrieve sales orders for a customer.
    
    Args:
        customer_id (str): Customer ID
        status (str, optional): Filter by status (Draft, Submitted, etc.)
        
    Returns:
        dict: List of orders with details
    """
    filters = {"customer": customer_id}
    if status:
        filters["status"] = status
        
    orders = frappe.get_all(
        "Sales Order",
        filters=filters,
        fields=["name", "grand_total", "status", "delivery_date"]
    )
    
    return {
        "customer_id": customer_id,
        "order_count": len(orders),
        "orders": orders
    }
 
@agent_tool(category="Inventory")
def check_item_availability(item_code: str, warehouse: Optional[str] = None) -> Dict:
    """
    Check item stock availability.
    
    Args:
        item_code (str): Item code to check
        warehouse (str, optional): Specific warehouse, or all if None
        
    Returns:
        dict: Stock levels and availability
    """
    filters = {"item_code": item_code}
    if warehouse:
        filters["warehouse"] = warehouse
        
    bins = frappe.get_all(
        "Bin",
        filters=filters,
        fields=["warehouse", "actual_qty", "reserved_qty"]
    )
    
    total_qty = sum(bin.actual_qty for bin in bins)
    total_reserved = sum(bin.reserved_qty for bin in bins)
    available = total_qty - total_reserved
    
    return {
        "item_code": item_code,
        "total_quantity": total_qty,
        "reserved_quantity": total_reserved,
        "available_quantity": available,
        "warehouses": [
            {
                "warehouse": bin.warehouse,
                "quantity": bin.actual_qty,
                "available": bin.actual_qty - bin.reserved_qty
            }
            for bin in bins
        ]
    }
 
@agent_tool(category="Pricing")
def calculate_order_total(items: List[Dict], customer_id: str) -> Dict:
    """
    Calculate total order amount with discounts and taxes.
    
    Args:
        items (list): List of items with 'item_code', 'qty', 'rate'
        customer_id (str): Customer ID for pricing rules
        
    Returns:
        dict: Calculated totals with breakdown
    """
    # Implementation
    subtotal = sum(item["qty"] * item["rate"] for item in items)
    
    # Get customer discount
    customer = frappe.get_doc("Customer", customer_id)
    discount_pct = customer.default_discount_percentage or 0
    discount_amount = subtotal * (discount_pct / 100)
    
    # Calculate tax (simplified)
    tax_rate = 0.10  # 10% tax
    tax_amount = (subtotal - discount_amount) * tax_rate
    
    total = subtotal - discount_amount + tax_amount
    
    return {
        "subtotal": round(subtotal, 2),
        "discount_percentage": discount_pct,
        "discount_amount": round(discount_amount, 2),
        "tax_rate": tax_rate,
        "tax_amount": round(tax_amount, 2),
        "grand_total": round(total, 2)
    }