[DOC] - Remote functions with `includes`

[hey-august]

Draft

# SWAIG Function Signatures

This document explains how the `get_signatures` functionality works in the SWAIG (SignalWire AI Gateway) framework and how function signatures are defined, requested, and used.

## Overview

SWAIG function signatures are metadata descriptions of API endpoints that allow AI systems to understand:
- What functions are available
- What parameters they accept
- What types of data they expect
- Which parameters are required or optional

The SWAIG framework automatically builds these signatures based on your function definitions and exposes them through the `get_signatures` action.

## Installation

Before using SWAIG, you need to install the required SignalWire packages:

```bash
# Install the core SWAIG framework
pip install signalwire-swaig

# Install SignalWire SWML 
pip install signalwire-swml

# Install SignalWire POM for prompt management (optional but recommended)
pip install signalwire-pom

These packages provide the following functionality:

• signalwire-swaig: Core framework for defining SWAIG endpoints
• signalwire-swml: Tools for working with SignalWire Markup Language (SWML)
• signalwire-pom: Prompt Object Model for managing AI prompts

Requesting Function Signatures

Request Format

To request function signatures, send a POST request to your SWAIG endpoint with the following JSON:

{
  "action": "get_signature",
  "functions": ["function_name1", "function_name2"] 
}

If the functions field is omitted or empty, all available function signatures will be returned.

Response Format

The response is an array of function signature objects, each containing:

[
  {
    "description": "Human-readable description of the function",
    "function": "function_name",
    "web_hook_url": "https://your-domain.com/swaig",
    "parameters": {
      "type": "object",
      "properties": {
        "param_name": {
          "type": "string",
          "description": "Description of the parameter",
          "default": "default_value"  // Optional
        },
        // Additional parameters...
      },
      "required": ["required_param1", "required_param2"]
    },
    // Optional function properties like active, wait_file, etc.
  },
  // Additional function signatures...
]

Defining Function Signatures

Function signatures are automatically generated from your endpoint definitions. Here's an example of how to define a function with its signature:

from signalwire_swaig.swaig import SWAIG, SWAIGArgument, SWAIGFunctionProperties

swaig = SWAIG(app)

@swaig.endpoint(
    description="Search for a movie by title or keywords",
    function_properties=SWAIGFunctionProperties(
        active=True,
        wait_for_fillers=True,
        fillers={"en": ["Let me search for that movie..."]}
    ),
    query=SWAIGArgument(
        type="string",
        description="The movie title or keywords to search for",
        required=True
    ),
    year=SWAIGArgument(
        type="integer",
        description="Filter by release year",
        required=False
    )
)
def search_movie(query, year=None, meta_data=None, meta_data_token=None):
    # Function implementation
    return "information about the movie", []

Parameter Types

The following parameter types are supported:

• string: Text values
• integer: Whole numbers
• number: Numeric values (including decimals)
• boolean: True/false values
• array: Lists of values (requires defining items)
• object: Nested objects (requires defining properties)

Examples

Example 1: Basic Function Signature Request

Request:

{
  "action": "get_signature",
  "functions": []
}

Response:

[
  {
    "description": "Search for a movie by title or keywords",
    "function": "search_movie",
    "web_hook_url": "https://myapp.com/swaig",
    "active": true,
    "wait_for_fillers": true,
    "fillers": {
      "en": ["Let me search for that movie..."]
    },
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The movie title or keywords to search for"
        },
        "year": {
          "type": "integer",
          "description": "Filter by release year"
        }
      },
      "required": ["query"]
    }
  }
]

Example 2: Specific Function Signature Request

Request:

{
  "action": "get_signature",
  "functions": ["create_reservation"]
}

Response:

[
  {
    "description": "Create a new reservation",
    "function": "create_reservation",
    "web_hook_url": "https://myapp.com/swaig",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Customer name"
        },
        "date": {
          "type": "string",
          "description": "Reservation date (YYYY-MM-DD)"
        },
        "time": {
          "type": "string",
          "description": "Reservation time (HH:MM)"
        },
        "party_size": {
          "type": "integer",
          "description": "Number of people"
        }
      },
      "required": ["name", "date", "time"]
    }
  }
]

Integration with AI Systems

These function signatures can be integrated with AI systems like SignalWire's SWAIG to enable natural language interfaces to your API endpoints. The AI will:

1. Request the available function signatures
2. Understand the available functions and their parameters
3. Match user intent to the appropriate function
4. Extract parameter values from natural language
5. Call your function with the extracted parameters

Function Includes

SWAIG supports including functions from other SWAIG endpoints through the "includes" mechanism. This allows you to reference and use functions defined in other services.

How Includes Work

When you include functions from another SWAIG service:

1. The AI agent can use functions from both your service and the included service
2. Your service acts as a proxy, forwarding requests to the included service
3. You can choose which specific functions to include

Example: Including Movie Database Functions

Here's an example of how to include movie-related functions from another service:

{
  "SWAIG": {
    "defaults": {
      "web_hook_url": "https://your-service.com/swaig"
    },
    "functions": [
      {
        "description": "Send a text message to the user",
        "function": "send_message",
        "parameters": {
          "properties": {
            "message": {
              "description": "The message to send via text message to the user",
              "type": "string"
            },
            "to": {
              "description": "The user's number in e.164 format",
              "type": "string"
            }
          },
          "required": [
            "message",
            "to"
          ],
          "type": "object"
        }
      }
    ],
    "includes": [
      {
        "functions": [
          "search_movie",
          "get_movie_details",
          "get_movie_recommendations",
          "get_trending_movies",
          "discover_movies"
        ],
        "url": "https://moviebot:password@moviebot.example.com/swaig"
      }
    ]
  }
}

In this example:

• Your service defines a send_message function locally
• It includes several movie-related functions from an external movie bot service
• The AI can now invoke both your local function and the movie functions

Python Configuration for Includes

To configure includes in your Python code, add them when setting up your AI prompt:

from signalwire_swml.swml import SignalWireSWML

swml = SignalWireSWML()

# Add your local SWAIG function
swml.add_aiswaigfunction({
    "description": "Send a text message to the user",
    "function": "send_message",
    # ...parameter definition...
})

# Add an include for external functions
swml.add_aiinclude({
    "url": "https://moviebot:password@moviebot.example.com/swaig",
    "functions": [
        "search_movie",
        "get_movie_details",
        # ...other functions...
    ]
})

Testing with SWAIG CLI

The signalwire-swaig package includes a command-line tool called swaig_cli that allows you to test your SWAIG functions. This is useful for:

• Verifying function signatures
• Testing function calls with different parameters
• Debugging your API endpoints
• Automating testing of your SWAIG services

Installing the CLI

The CLI is installed automatically when you install the signalwire-swaig package:

pip install signalwire-swaig

Getting Function Signatures

To retrieve function signatures from your SWAIG server:

# Get all function signatures
swaig_cli --url http://username:password@localhost:5000/swaig --get-signatures

# Get a specific function signature
swaig_cli --url http://username:password@localhost:5000/swaig --get-signatures --function search_movie

Example output:

[
  {
    "description": "Search for a movie by title or keywords",
    "function": "search_movie",
    "web_hook_url": "https://myapp.com/swaig",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The movie title or keywords to search for"
        },
        "year": {
          "type": "integer",
          "description": "Filter by release year"
        }
      },
      "required": ["query"]
    }
  }
]

Testing Function Calls

To test a function call with the CLI:

# Interactive mode - CLI will prompt for parameters
swaig_cli --url http://username:password@localhost:5000/swaig --function search_movie

# Provide parameters as JSON
swaig_cli --url http://username:password@localhost:5000/swaig --function search_movie --json '{"query": "Inception", "year": 2010}'

# Include metadata
swaig_cli --url http://username:password@localhost:5000/swaig --function search_movie --json '{"query": "Inception"}' --meta-data '{"user_id": "12345"}'

When running in interactive mode, the CLI will prompt you for each parameter based on the function signature:

Enter query (string) - The movie title or keywords to search for: Inception
Enter year (integer) - Filter by release year [optional]: 2010

Sending request to server...
{
  "function": "search_movie",
  "argument": {
    "parsed": [
      {
        "query": "Inception",
        "year": 2010
      }
    ]
  },
  "meta_data": {},
  "meta_data_token": "swaig-cli"
}

Server Response:
{
  "response": "information about the movie",
  "action": []
}

Automating Tests

You can use the CLI in scripts to automate testing of your SWAIG functions:

#!/bin/bash

# Test search_movie function
swaig_cli --url http://username:password@localhost:5000/swaig --function search_movie --json '{"query": "Inception"}' > test_results.json

# Verify the response
if grep -q "information about the movie" test_results.json; then
  echo "Test passed: search_movie returned expected result"
else
  echo "Test failed: search_movie did not return expected result"
  exit 1
fi

# Test more functions...

CLI Options

The SWAIG CLI supports the following options:

Option	Description
--url	The SWAIG server URL (required)
--get-signatures	Get function signatures
--function	Test a specific function by name
--json	JSON string containing function arguments
--meta-data	Additional metadata to include in the request

Important Notes

• Signature data is automatically generated from your endpoint definitions
• Changes to function parameters require updating the endpoint decorator
• The SWAIGArgument class defines parameter metadata (type, description, etc.)
• Function properties defined with SWAIGFunctionProperties control additional behavior
• The web_hook_url is automatically set by the framework

[Devon-White]

Guide above is written fromt he perspective of using the SWIAG library Brian included. While its helpful, it does not explain how to actually use and setup remote functions.

The above guide does cover the get_signatures but a lot of the logic is missing because the library abstracts that for you. For the sake of the includes page, we should write this from the perspective of not using a library, but reference the libraries and mention how it makes getting started easier.

Edit: Make Includes reference page show to handle get_signature request without library, guides utilize library.