Download the PHP package moe-mizrak/laravel-prompt-alchemist without Composer

Laravel Prompt Alchemist

Versatile LLM Tool Use (Function Calling) package for Laravel, compatible with all LLMs, enabling LLM to execute actual code functions (unlike LLMs' built-in capabilities).

Unlock Powerful Large Language Model (LLM) Interactions in Your Laravel Application.

This Laravel package enables versatile LLM Tool Use (Function Calling), allowing LLMs to decide and execute function calls based on the prompt. Unlike built-in capabilities that may only list functions, this package makes the actual calls, ensuring dynamic execution. Compatible with all LLMs, it enhances automation and interactivity in your applications.

Table of Contents

• 🤖 Requirements
• 🏁 Get Started
• ⚙️ Configuration
• ⚡ Quick Usage Guide
• 🎨 Usage
  • Using Facade
    • Generate Function List
      • Manually create function list
      • Use generateFunctionList method
    • Define Function Signature Mapping
    • Generate Prompt Function Instructions
    • Define Schemas
      • Function Payload Schema
      • Function Results Schema
    • Prepare Prompt Function Payload
    • Send Tool Use (Function Calling) Request to OpenRouter
    • Validate Function Signature
    • Call Function (Actual Function Call)
    • Prepare Function Results Payload
    • Send Function Results to OpenRouter
  • Using PromptAlchemistRequest Class
• 💫 Contributing
• 📜 License

🤖 Requirements

• PHP 8.1 or higher
• Laravel Openrouter

  ℹ️ OpenRouter is used as the default LLM provider in the package. The package is structured flexibly, allowing you to use your choice of LLM provider such as OpenAI, Claude, Gemini etc. (OpenRouter is a unified interface for LLMs.)

🏁 Get Started

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

⚙️ Configuration

After publishing the package configuration file, steps you should be following:

➡️ env_variables Add following environment variables to your .env file in case you will be using OpenRouter as LLM provider (If your choice of LLM provider is different, then this is not required):

• OPENROUTER_API_ENDPOINT: The endpoint URL for the OpenRouter API (default: https://openrouter.ai/api/v1/).
• OPENROUTER_API_KEY: Your API key for accessing the OpenRouter API. You can obtain this key from the OpenRouter Dashboard. (e.g. sk-or-v1... )
• OPENROUTER_DEFAULT_MODEL: Default model that will be used in the package - necessary for generateInstructions functionality (In codebase, you can still specify any model that you want for OpenRouter requests). You can check model list from OpenRouter Models. (e.g. 'mistralai/mistral-7b-instruct:free')

➡️ functions_yml_path Add path of the functions yml file which is the callable function list of your project. The Generate Function List section provides a deep dive into functions yml file; how to define functions, format needs to be used etc. (e.g. __DIR__ . '/../resources/functions.yml').

➡️ function_signature_mapping: Add mapping for function signature namings. The Define Function Signature Mapping section provides a deep dive into function signature mapping. (e.g. )

➡️ schemas Add path of the schemas needed for function payload and function results payload.

• function_payload_schema_path: Path of the function payload schema. The Function Payload Schema section provides a deep dive into function payload schema. (e.g. __DIR__ . '/../resources/schemas/function_payload_schema.yml')
• function_results_schema_path: Path of the function results schema. The Function Results Schema section provides a deep dive into function results schema. (e.g. __DIR__ . '/../resources/schemas/function_results_schema.yml')

➡️ instructions: Add instructions for prompt_function_instructions, function_results_instructions and generate_prompt_function_instructions.

• prompt_function_instructions: Instructions for the LLM used for prompt function payload. The Generate Prompt Function Instructions section provides a deep dive into prompt function instructions. (e.g. You are an AI assistant that strictly follows instructions and provides response ...)
• function_results_instructions: Instructions for the LLM used for function results payload. The Prepare Function Results Payload section provides a deep dive into function results instructions. (e.g. You will strictly follow the instructions as ...)
• generate_prompt_function_instructions: Instructions for generating prompt_function_instructions by using generateInstructions function. The Generate Prompt Function Instructions section provides a deep dive into generating prompt function instructions. (e.g. Your role is to analyze the provided "functions" and ...)

⚡ Quick Usage Guide

This package is designed to be flexible, but for an easy quick start, follow the steps below:

• Create a file named functions.yml under a directory of your choice. Modify config file accordingly for functions_yml_path. (Check Generate Function List for further details).

• Generate function list as in Use generateFunctionList method. It automatically adds functions to functions.yml file with all possible function signature details/descriptions considering also function's docblock.
  

(Add all classes and functions that LLM should take into account for its decisions, as much info as possible in FunctionData for better performance):

• Create yml file for function payload schema and modify function_payload_schema_path in config accordingly. (Check Function Payload Schema for further details).
  

Sample function_payload_schema.yml as:

Config file path for function_payload_schema_path:

• Add OPENROUTER_API_KEY, OPENROUTER_DEFAULT_MODEL and OPENROUTER_API_ENDPOINT in your env file - as defined in env_variables in config (OPENROUTER_API_ENDPOINT already has default value which can be skipped, OPENROUTER_API_KEY and OPENROUTER_DEFAULT_MODEL should be set as described in Configuration section.)
• Leave prompt_function_instructions in config untouched or check out Generate Prompt Function Instructions in order to generate customized new instructions.

• Make Laravel OpenRouter request for Tool Use (Function Calling) so that LLM will make decision which functions to call for the given prompt. (Note: Laravel OpenRouter already comes with this package - as default LLM provider - so no need for a separate installation)

• Validate the response retrieved from OpenRouter. (Check Validate Function Signature for further details).
  

Sample LLM returned functions:

Invoke validateFunctionSignature for function signature validation of $llmReturnedFunctionData:

• And finally, call functions returned from the LLM which are necessary for answering the prompt (Since function signature is validated, it is now safe to call LLM returned functions). (Check Call Function (Actual Function Call) for further details).
  

(Note: You need to set parameter values to be able to call the function. Required parameters have to be set, otherwise ErrorData is returned. It is a better practice to set the parameter values as checking validateFunctionSignature since type of provided values also gets validated if set, but it can also be done in this step.)

Set parameter values before calling function as below.

Call the function as following:

Sample function result ($functionResultData) DTO object:

Where function_name is the name of the function called as the name suggested, and result is the function call result can be anything (void, array, object, bool etc. whatever your function returns to.)

• Optionally, you can also send function results to LLM so that regarding function_results_schema, it will return the answer. (Check Prepare Function Results Payload for further details)

Where $response is the function_results_schema formed answer returned from the LLM according to function_results_instructions.

🎨 Usage

This package provides two ways to interact with the Laravel Prompt Alchemist package:

• Using the LaravelPromptAlchemist facade (i.e. Using Facade).
• Instantiating the PromptAlchemistRequest class directly (i.e. Using PromptAlchemistRequest Class).

Using Facade

The LaravelPromptAlchemist facade offers a convenient way to make Laravel Prompt Alchemist requests. Following sections will lead you through further configuration and usage of LaravelPromptAlchemist facade.

Generate Function List

In order to generate function list (functions.yml), you can either:

Manually create function list

Create function signatures manually using your chosen naming convention in a flat associative array structure.

ℹ️ Ensure coherence with function_signature_mapping, which aligns your naming practices with the package format for integration. (Note: Please refer to Define Function Signature Mapping section for which function signatures should be defined in function list yml file for better performance)

• Create yml file for function list with any preferred naming and directory.
  

e.g. You can create a file named functions.yml in the resources folder under your project

• Define functions in yml file that you will be using for the package (for Tool Use - Function Calling).
  

e.g. You can create functions as samples below in a flat associative array structure or your choice of function naming convention.

Recommended naming convention (generateFunctionList method for generating a function list, also outputs the function list in this format):

Or, another naming convention in a flat associative array structure can be as:

Use generateFunctionList method

Use generateFunctionList function to generate a detailed function list from a given class and write it to a file in yml format.
(For each different class name, you need to run the generateFunctionList to generate function list - functions.yml, list gets appended whenever the generateFunctionList is called)

ℹ️ This is a good practice to automate the generation of function list. The fields that are defined in the function description (functionData) overwrites the function predefined fields if exists. If a function signature field is missing then it is added to function list definitions.

Alternative way for creating the functions array; when function signatures and docblock are well-defined, simply adding function names suffices to create a comprehensive function list:

Sample of well-defined function signature and docblock. (Docblock description with enough info, type-hinted params, return type declaration and return tag description in docblock, parameter descriptions in docblock):

Sample of poorly-defined function signature and docblock. (no docblock, no type-hint for params, no return type declaration):

Sample of partially-defined function signature and docblock:

Based on your best practices in your codebase, you can choose how to generate function list (functions.yml).

1. If functions are well-defined in your codebase, you can use alternative approach to send the function names in functions array with no additional info (generateFunctionList does everything for you).
2. If functions are poorly-defined in your codebase, then it is best to use the main approach by creating FunctionData DTO for each function and setting function related info/descriptions to create functions array.
3. If functions are partially-defined in your codebase, then similarly using the main approach is the best option since more info is better for LLM to know about your functions to make the best decision.
   

Note: You can just add missing/ambiguous/poorly-defined fields in FunctionData DTO and skip the descriptions/fields that are well-defined since generateFunctionList analyses function and adds all possible information about the function. Also note that fields added to FunctionData DTO overwrite the existing predefined descriptions/fields in the function . (Basically if a field is added to FunctionData DTO, it is taken into account; if a field is NOT added to FunctionData and exists in function declaration then this predefined description/field is added to function list).

Define Function Signature Mapping

Based on the function list (functions.yml), align your naming practices for functions with the package format for integration. It is better practice to set all possible fields for function signature (FunctionSignatureMappingData) for better performance since more info provided for LLM means better result.

function_signature_mapping needs to be defined in the config file as following examples:

(As shown in examples below, use '[]' for the arrays. In package, it is replaced with the index key as e.g. parameters[].name becomes parameters.{key}.name which is parameters.0.name for the first array index, parameters.1.name for the second etc.)

• In case your function list (functions.yml) is created with recommended naming convention:

• If your function list (functions.yml) is created with another naming convention:

Regarding these 2 examples, you can define your function_signature_mapping in the configuration file depending on your choice of naming convention.

Generate Prompt Function Instructions

This section defines the instructions which gives strict description of desired format answers and how LLM provider will process provided prompt, schemas etc.

You can use your own created/generated instructions for prompt_function_instructions, or use generateInstructions method.

generateInstructions method simply generates customized instructions regarding your function list (functions.yml), function payload schema (function_payload_schema.yml) and prompt for generating instructions (generate_prompt_function_instructions in config).

(Note: generate_prompt_function_instructions is the prompt/instructions in config that describe how to generate specific/customized instructions with functions and function_payload_schema)

Sample generate_prompt_function_instructions for generateInstructions call:

In order to generate prompt_function_instructions, you can call generateInstructions method:

Sample response of generateInstructions will look like:

Define Schemas

This section defines the desired schema samples that are used for formatting the function payload and function results. Basically schemas are for deciding the response format of LLM. They are sent to LLM along with other info (prompt, functions - function results, instructions etc.) and in instructions LLM asked to give results as same format as in schema provided. In this way, LLM response can be resolved in package so that it can be used for Tool Use (Function Calling).

Function Payload Schema

Schema that defines the structure of the function payload.

• Create yml file for function payload schema with any preferred naming and directory, add it to config file under schemas.

• Define schema as example given below. The naming convention should align with the function list (functions.yml) because LLM response will depend on this schema and response will be validated in the package by comparing the function list (functions.yml) file.

Function Results Schema

Schema that defines the structure of the function results. This schema is for deciding the final response where function results are sent to LLM to form the response after Tool Use (Function Calling).

This schema is not required if you will not be sending function call results to LLM. You might prefer using function results in your codebase to derive a response directly.

• Create yml file for function results schema with any preferred naming and directory, add it to config file under schemas.

• Define schema as example given below.

Prepare Prompt Function Payload

This method is responsible for creating a structured payload template based on a given prompt and a list of functions (functions.yml) which later will be sent to an LLM provider. This method constructs an array containing instructions, the prompt, a list of functions, and a function payload schema. The instructions detail how the prompt should be processed, ensuring the response strictly adheres to the provided format.

For the prompt which you will be used for Tool Use (Function Calling):

This is how you can call preparePromptFunctionPayload method by using facade:

And this is the expected prepared payload response sample:

Send Tool Use (Function Calling) Request to OpenRouter

Since this package is designed in a flexible way, you may use Laravel OpenRouter (please check out OpenRouter github repository for more information) which is used as the default LLM provider for this package, or you may use any other LLM provider with this package to send Tool Use (Function Calling) request.
This is the sample OpenRouter request:

Sample Laravel OpenRouter response (ResponseData is returned):

Validate Function Signature

Validates a function signature returned by the LLM. It returns boolean or ErrorData for wrong function signature with missing/wrong field. You can retrieve LLM returned functions from ResponseData returned by Send Tool Use (Function Calling) Request to OpenRouter.
Sample LLM returned functions:

And this is how to validate a function signature returned from LLM (formed llm returned function as above, also values are set for parameters):

In case the LLM returned function signature is invalid, this is a sample ErrorData returned:

Call Function (Actual Function Call)

This method make actual function call with provided function signatures along with values for parameters. Since Validate Function Signature step). Regardless of the function visibility (private, protected, public etc.), function can be called directly.

This package makes actual function calls unlike built-in capabilities of LLMs that may only list functions. Basically with this package, you can get the list of the functions regarding your prompt from LLM, and then make an actual function calls to retrieve function results.

This is how to call function:

Result is returned as FunctionResultData DTO object as a sample result given below:

Where function_name is the name of the function called, result is whatever this function returns (array, bool, int, mixed, object, void etc.)

Prepare Function Results Payload

This method is responsible for creating a structured payload template based on a given prompt and a function results which later will be sent to an LLM provider. This method constructs an array containing instructions, the prompt, a function results, and a function results schema. The instructions detail how the prompt should be processed, ensuring the response strictly adheres to the provided format as function results schema.

Prompt which will be used for function results payload preparation:

This is how you can call prepareFunctionResultsPayload method by using facade:

And this is the expected prepared function results payload sample:

Send Function Results to OpenRouter

Since this package is designed in a flexible way, you may use Laravel OpenRouter (please check out OpenRouter github repository for more information) which is used as the default LLM provider for this package, or you may use any other LLM provider with this package to send Tool Use (Function Calling) request.
This is the sample OpenRouter request for function results:

Sample Laravel OpenRouter response (ResponseData is returned):

Using PromptAlchemistRequest Class

You can also inject the PromptAlchemistRequest class in the constructor of your class and use its methods directly.

While everything else stays same with the Using Facade, with PromptAlchemistRequest you can call methods as following:

💫 Contributing

We welcome contributions! If you'd like to improve this package, simply create a pull request with your changes. Your efforts help enhance its functionality and documentation.

📜 License

Laravel Prompt Alchemist is an open-sourced software licensed under the MIT license.