lollms-webui/docs/function_calls/doc.md

LoLLMS Function Calls Documentation

Overview

The LoLLMS Function Calls system allows Large Language Models (LLMs) to interact with external functions and tools. This system enables the AI to perform tasks beyond text generation, such as retrieving real-time information, performing calculations, or interacting with external APIs.

Key Concepts

1. Function Zoo: A directory containing all available functions
2. Mounted Functions: Functions currently enabled for use by the LLM
3. Function Call Format: Special JSON format for invoking functions
4. Processing Types:
   • Direct Execution (needs_processing=False)
   • AI Interpretation (needs_processing=True)

System Architecture

graph TD
    A[User Prompt] --> B[Prompt Enhancement]
    B --> C[LLM Processing]
    C --> D{Function Call Detected?}
    D -->|Yes| E[Function Execution]
    D -->|No| F[Direct Response]
    E --> G{needs_processing?}
    G -->|Yes| H[AI Interpretation]
    G -->|No| I[Direct Output]
    H --> J[Final Response]
    I --> J
    F --> J

Function Call Lifecycle

1. Prompt Enhancement: System adds function descriptions to user prompt
2. LLM Processing: AI generates response, potentially including function calls
3. Function Detection: System extracts and validates function calls
4. Execution: Selected functions are executed with provided parameters
5. Result Processing: Output is either shown directly or processed by AI
6. Final Response: Combined output is presented to user

Creating New Functions

Step 1: Create Function Directory

1. Navigate to functions zoo:

   cd {lollms_functions_zoo_path}
   

2. Create new directory:

   mkdir my_function
   cd my_function
   

Step 2: Create Configuration File (config.yaml)

name: my_function
description: Brief description of what the function does
parameters:
  param1:
    type: string
    description: Description of parameter
  param2:
    type: number
    description: Another parameter
returns:
  result1:
    type: string
    description: Description of return value
examples:
  - "Example usage 1"
  - "Example usage 2"
needs_processing: true/false
author: Your Name
version: 1.0.0

Step 3: Implement Function Logic (function.py)

class MyFunction:
    def __init__(self, lollmsElfServer):
        self.lollmsElfServer = lollmsElfServer
        
    def run(self, **kwargs):
        """
        Main function logic
        Returns: Dictionary containing results
        """
        # Access parameters
        param1 = kwargs.get('param1')
        param2 = kwargs.get('param2')
        
        # Your logic here
        result = perform_operation(param1, param2)
        
        return {
            "result1": result,
            "status": "success"
        }

Step 4: Mount the Function

1. Add to mounted functions list in configuration
2. Or use API endpoint:

   POST /mount_function_call
   {
       "client_id": "your_client_id",
       "function_name": "my_function"
   }
   

Function Call Format

AI-Generated Format

<lollms_function_call>
{
    "function_name": "function_name",
    "parameters": {
        "param1": "value1",
        "param2": "value2"
    },
    "needs_processing": true/false
}
</lollms_function_call>

Response Format

{
    "function_name": "function_name",
    "parameters": {
        "param1": "value1",
        "param2": "value2"
    },
    "results": {
        "result1": "value1",
        "result2": "value2"
    },
    "status": "success/error",
    "message": "Additional information"
}

API Endpoints

1. List Available Functions

   GET /list_function_calls
   

2. List Mounted Functions

   GET /list_mounted_function_calls
   

3. Mount Function

   POST /mount_function_call
   {
       "client_id": "your_client_id",
       "function_name": "function_name"
   }
   

4. Unmount Function

   POST /unmount_function_call
   {
       "client_id": "your_client_id",
       "function_name": "function_name"
   }
   

Best Practices

1. Error Handling: Implement robust error handling in your function
2. Parameter Validation: Validate all inputs before processing
3. Security: Sanitize all inputs and outputs
4. Documentation: Provide clear examples and descriptions
5. Versioning: Maintain version numbers for compatibility
6. Performance: Optimize for quick execution
7. Idempotency: Make functions repeatable without side effects

Example: Weather Function

config.yaml

name: get_weather
description: Get current weather information
parameters:
  location:
    type: string
    description: City name or coordinates
  unit:
    type: string
    enum: [celsius, fahrenheit]
    default: celsius
returns:
  temperature:
    type: number
  condition:
    type: string
examples:
  - "What's the weather in Paris?"
  - "How's the weather today?"
needs_processing: true
author: Weather Inc.
version: 1.2.0

function.py

import requests

class WeatherFunction:
    def __init__(self, lollmsElfServer):
        self.lollmsElfServer = lollmsElfServer
        self.api_key = "your_api_key"
        
    def run(self, **kwargs):
        location = kwargs.get('location', 'Paris')
        unit = kwargs.get('unit', 'celsius')
        
        try:
            response = requests.get(
                f"https://api.weatherapi.com/v1/current.json?key={self.api_key}&q={location}"
            )
            data = response.json()
            
            return {
                "temperature": data['current']['temp_c'] if unit == 'celsius' else data['current']['temp_f'],
                "condition": data['current']['condition']['text'],
                "location": location,
                "unit": unit,
                "status": "success"
            }
        except Exception as e:
            return {
                "status": "error",
                "message": str(e)
            }

This documentation provides a comprehensive guide to understanding, creating, and managing function calls in the LoLLMS system. Follow these guidelines to extend the capabilities of your LLM with custom functions.