Download the PHP package ogi/prompt without Composer

Prompt

A PHP package that transforms class properties into XML-formatted prompts, ready for Large Language Model (LLM) API calls. It recursively handles arrays, collections, nested arrays, and nested Prompt instances, converting them into XML with appropriate tags.

Why XML Structured Prompts?

Structured prompts are essential when interacting with Large Language Models (LLMs) to ensure consistency, clarity, and optimal performance. XML provides a standardized way to structure data, making it an excellent choice for formatting prompts:

• Consistency Across Models: XML's hierarchical structure allows for consistent formatting of prompts, which can be beneficial when working with different models or APIs.
• Improved Parsing: XML is a widely accepted format that can be easily parsed and validated, reducing the likelihood of errors in prompt interpretation.
• Flexibility: XML's ability to represent complex nested data makes it suitable for constructing detailed and intricate prompts.
• Readability: Structured XML prompts are more readable and maintainable, aiding in debugging and prompt optimization.

By using XML-formatted prompts, developers can provide clear and unambiguous instructions to LLMs, potentially enhancing the models' understanding and response accuracy.

Table of Contents

• Installation
• Features
• Usage
  • Basic Example
  • Handling Arrays
  • Using Collections
  • Nested Prompt Instances
  • Using the GeneralPromptTemplate
  • Custom Objects with toArray() or __toString__
  • Handling Special Cases
  • Private and Protected Properties
  • Null and Empty Values
  • Boolean Values
  • Numeric Values
  • Special Characters
  • Objects Without toArray() or __toString__
  • Circular References
• Testing
• Contributing
• License
• Additional Notes

Installation

Install the package via Composer:

Features

• Automatic XML Conversion: Transforms public class properties into XML elements.
• Array and Collection Handling: Supports arrays, collections, and nested arrays, using <entry> and <list> tags where appropriate.
• Nested Prompt Instances: Allows properties to be instances of Prompt, rendering them recursively within <prompt> tags.
• Custom Object Support: Handles objects implementing toArray() or __toString().
• Edge Case Handling: Manages special cases like private/protected properties, null values, booleans, numerics, special characters, and circular references.
• Recursive Processing: Recursively processes nested arrays and collections to any depth.
• Easy Integration: Extend the Prompt class and define your data; the render() method handles the rest.
• Templates: Extend the GeneralPromptTemplate class and leverage its setters to populate a versatile, general-use template prompt for your data.

Usage

Basic Example

Create a PHP class that extends the Prompt class provided by the package. Define your data using public properties.

Output:

Handling Arrays

The package automatically handles arrays and converts them into XML using <entry> and <list> tags.

Output:

Using Collections

The package supports any object that implements the Traversable interface, such as PHP's ArrayObject or collections from frameworks like Laravel's Illuminate\Support\Collection.

Output:

Nested Prompt Instances

You can have properties that are instances of the Prompt class. These will be rendered recursively within <prompt> tags.

Output:

Using the GeneralPromptTemplate

The GeneralPromptTemplate is an abstract class that allows you to define more structured prompts with context, purpose, goals, and instructions for input and output. You can extend this class and set properties to generate XML prompts.

Output:

Custom Objects with toArray() or __toString__

The package can handle custom objects that implement toArray() or __toString().

Objects with toArray()

Output:

Objects with __toString()

Output:

Handling Special Cases

Private and Protected Properties

Only public properties are included in the XML output. Private and protected properties are excluded.

Output:

Null and Empty Values

Properties with null values or empty arrays are handled gracefully.

Output:

Boolean Values

Boolean values are converted as follows:

• true becomes 1
• false becomes an empty string

Output:

Numeric Values

Numeric values are converted to strings and included in the output.

Output:

Special Characters

Special characters are properly escaped to produce valid XML.

Output:

Objects Without toArray() or __toString__

Objects that cannot be converted to a string or array are represented as empty tags.

Output:

Circular References

The package handles circular references gracefully to prevent infinite recursion.

Output:

Testing

The package includes a comprehensive test suite using PHPUnit to ensure reliability and correctness. Tests cover:

• Inclusion of public properties and exclusion of private/protected ones.
• Handling of null values, empty arrays, booleans, numerics, and special characters.
• Processing of objects with and without toArray() or __toString__.
• Recursive rendering of nested Prompt instances.
• Edge cases like circular references and mixed-type arrays.

Running Tests

To run the tests, execute:

Or if you have added a Composer script:

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or bugfix.
3. Write tests for your changes.
4. Ensure all tests pass.
5. Submit a pull request with a detailed description of your changes.

License

This project is licensed under the MIT License.

Additional Notes

• PHP Version: Ensure your PHP version is 7.4 or higher.
• Dependencies: If you use collections from frameworks like Laravel, make sure to include the necessary packages (e.g., illuminate/support).
• Circular References: Circular references are detected to prevent infinite loops during rendering.

Need Help?

If you have any questions or need assistance, please open an issue on the GitHub repository.

Happy Coding!