[Enhancement] Add @deepgram_tool decorator for streamlined Voice Agent function registration

[deepgram-robot]

Summary

Add a @deepgram_tool decorator that automatically generates the JSON Schema function definition from a Python function's type hints and docstring, enabling single-line Voice Agent tool registration without manual schema authoring.

Problem it solves

Registering functions for Voice Agent tool calling currently requires manually writing JSON Schema definitions — specifying parameter names, types, descriptions, and required fields in a separate dictionary. This is error-prone, tedious for functions with many parameters, and duplicates information already present in Python type hints and docstrings. Developers building voice agents with multiple tools spend significant time on boilerplate schema definitions that could be auto-generated.

Proposed API

from deepgram import deepgram_tool

@deepgram_tool(description="Look up a customer's order status by order ID")
def get_order_status(order_id: str, include_tracking: bool = False) -> str:
    """Retrieves the current status of an order.

    Args:
        order_id: The unique order identifier (e.g., ORD-12345)
        include_tracking: Whether to include shipping tracking details
    """
    return db.get_order(order_id).format(tracking=include_tracking)

# Auto-generates equivalent of:
# {
#   "name": "get_order_status",
#   "description": "Look up a customer's order status by order ID",
#   "parameters": {
#     "type": "object",
#     "properties": {
#       "order_id": {"type": "string", "description": "The unique order identifier"},
#       "include_tracking": {"type": "boolean", "description": "Whether to include shipping tracking details"}
#     },
#     "required": ["order_id"]
#   }
# }

# Registration:
agent.register_tools([get_order_status])
# or: tools = [get_order_status.schema]  # access the generated schema

Acceptance criteria

• Decorator extracts function name, description, and parameter schema from type hints
• Supports str, int, float, bool, list, dict, and Optional types
• Parses Google-style and NumPy-style docstrings for parameter descriptions
• Handles default values (parameters with defaults are not required)
• Generated schema is compatible with Voice Agent API function calling format
• .schema property exposes the raw JSON Schema dict for manual use
• Documented with usage example
• Compatible with existing API (non-breaking addition)

---

Raised by the DX intelligence system.