PHPackages poml/toolkit - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. poml/toolkit ActiveProject[Utility & Helpers](/categories/utility) poml/toolkit ============ POML Toolkit 00PHP Since Sep 15Pushed 8mo agoCompare [ Source](https://github.com/kuasarx/POML-Toolkit)[ Packagist](https://packagist.org/packages/poml/toolkit)[ RSS](/packages/poml-toolkit/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) POML Toolkit ============ [](#poml-toolkit) Overview -------- [](#overview) The POML Toolkit is a PHP-based orchestration engine designed to manage complex prompt workflows using a custom XML-based language called POML (Prompt Orchestration Markup Language). Its primary purpose is to enable developers to define, parse, and execute multi-step AI prompt chains that integrate with language models, custom tools, conditional logic, and state management. This toolkit is particularly useful for building AI-driven applications where prompts need to be sequenced, variables extracted from responses, and decisions made based on runtime conditions. ### Key Features [](#key-features) - **Prompt Execution**: Send prompts to AI models via connectors (e.g., dummy for testing or HTTP for real APIs like OpenAI). - **Tool Integration**: Call PHP functions as tools within the workflow, with parameter resolution from state. - **Conditional Logic**: Support for if/else steps with simple condition evaluation (e.g., `{{var}} == 'value'`). - **Variable Extraction**: Automatically extract values from JSON responses into state variables. - **State Management**: Persistent state across steps for variable sharing and result tracking. - **Error Handling**: Custom exceptions for engine and parser errors. ### Architecture [](#architecture) The toolkit follows a modular design with the following core components: - **Steps (Implement StepInterface)**: Abstract interface for executable steps. - `PromptStep`: Executes a prompt via a connector and extracts variables. - `ToolStep`: Invokes a registered PHP callable with resolved parameters. - `ConditionalStep`: Evaluates a condition and executes then/else branches. - **Orchestration**: Container for a sequence of steps parsed from POML XML. - **Connectors (Implement ModelConnectorInterface)**: Interfaces for AI model interactions. - `DummyConnector`: For testing, returns predefined responses. - `HttpConnector`: For real HTTP-based API calls (e.g., to OpenAI). - **PomlParser**: Parses POML XML using SimpleXML, validating structure and building step objects. - **OrchestrationEngine**: Central executor that registers connectors/tools, runs the orchestration, and manages state via `StateManager`. - **StateManager**: Handles variable resolution (e.g., `{{var}}`), storage, and retrieval. - **Exceptions**: `EngineException` for runtime errors, `ParserException` for XML issues. ### Dependencies [](#dependencies) From `composer.json`: - PHP ^8.0 (strict types enforced). - Autoloading via PSR-4 for `Poml\Toolkit\` namespace mapping to `src/`. No external libraries are required beyond PHP's built-in extensions (e.g., SimpleXML for parsing, cURL implicitly via HTTP connector if used). ### Architecture Diagram [](#architecture-diagram) ``` graph TD A[Poml XML Input] --> B[PomlParser] B --> C[Orchestration Object with Steps] C --> D[OrchestrationEngine] D --> E[Register Connectors and Tools] E --> F[Run Orchestration] F --> G[StateManager for Variables and Results] G --> H[Execute Steps: Prompt, Tool, Conditional] H --> I[Connectors: Dummy or HTTP] I --> J[Tools: PHP Callables] J --> G H --> K[Variable Extraction from JSON] K --> G L[Conditional Evaluation] --> M[Then/Else Branches] M --> H ``` Loading Implemented Changes and Improvements ------------------------------------ [](#implemented-changes-and-improvements) This version includes several enhancements based on best practices for robustness and maintainability: - **Autoloader Improvements**: Switched to PSR-4 compliant autoloading for better namespace organization and Composer integration. - **Error Handling Refactor**: Introduced specific exceptions (`EngineException`, `ParserException`) instead of generic ones. For example, connector/tool not found throws `EngineException`; invalid XML throws `ParserException` with detailed libxml errors. - **Step Refactorizations**: `StepInterface` now enforces a clean `execute(StateManager $state): mixed` contract. Subclasses like `PromptStep` handle JSON decoding safely with `json_last_error()` checks. `ConditionalStep` uses regex for simple condition parsing (e.g., equality checks) with fallback to truthy evaluation. - **Optimizations**: Parsing uses efficient SimpleXML with internal error suppression and clear/reset. Engine execution avoids recursion depth issues by linear step processing; conditional branches are executed sequentially without loops. Variable resolution in `StateManager` (not shown but inferred) uses string replacement for efficiency. These changes improve reliability, reduce boilerplate, and enhance debuggability. Installation Instructions ------------------------- [](#installation-instructions) 1. **Prerequisites**: Ensure PHP 8.0+ is installed with SimpleXML extension enabled. 2. **Clone or Download**: Place the project in your workspace (e.g., `c:/Users/kuasa/Documents/VScode/poml`). 3. **Install Dependencies**: ``` composer install ``` This sets up the autoloader; no additional packages are needed. 4. **Configuration**: - For testing: No setup required (uses DummyConnector). - For real AI models: Set environment variables, e.g., `export OPENAI_API_KEY=your_key_here` (or use `putenv()` in PHP). - Edit connectors in code if needed (e.g., register `HttpConnector` with API URL and key). 5. **Execution**: - Run the example: `php example.php` - This parses a sample POML XML, registers a tool and connector, and executes the workflow, printing outputs. If issues arise (e.g., missing extensions), check PHP error logs. Usage Examples -------------- [](#usage-examples) The `example.php` demonstrates a full workflow: generating JSON, extracting a variable, and conditionally calling a tool. ``` Generate a JSON object with a user 'name' and a 'status' of 'active'. User is active, proceeding to next step. User is not active, aborting. XML; // 3. Set up the Orchestration Engine $engine = new OrchestrationEngine(); $parser = new PomlParser(); // 4. Register tools and connectors $engine->registerTool('notify', 'send_notification'); // Use a DummyConnector that returns a valid JSON for this example. class JsonDummyConnector extends DummyConnector { public function execute(string $prompt): string { return '{"name": "John Doe", "status": "active"}'; } } $engine->registerConnector('json-generator', new JsonDummyConnector()); /* To use a real HTTP endpoint, you would do this instead: $apiKey = getenv('OPENAI_API_KEY'); // It's best practice to use environment variables $apiUrl = 'https://api.openai.com/v1/chat/completions'; $engine->registerConnector( 'gpt-4', new HttpConnector($apiUrl, 'gpt-4', $apiKey) ); */ // 5. Parse and run the orchestration try { echo "Parsing POML...\n"; $orchestration = $parser->parse($pomlXml); echo "Running orchestration...\n\n"; $finalResult = $engine->run($orchestration); echo "\nOrchestration finished.\n"; echo "Final Result (from 'last_result'): " . print_r($finalResult, true) . "\n"; } catch (\Exception $e) { echo "\nAn error occurred: " . $e->getMessage() . "\n"; echo "Trace: \n" . $e->getTraceAsString() . "\n"; } ?> ``` Expected output includes parsed POML execution, notification sent, and final result. ### Best Practices [](#best-practices) - **Environment Variables**: Always use `getenv()` for sensitive data like API keys to avoid hardcoding. - **Input Validation**: In custom tools, validate parameters to prevent injection attacks (e.g., sanitize strings). - **Error Handling**: Wrap `run()` in try-catch to handle `EngineException` or `ParserException` gracefully. - **Testing**: Use `DummyConnector` for unit tests; mock responses for integration. - **Scalability**: For complex workflows, break into multiple orchestrations; monitor state size to avoid memory issues. - **POML Design**: Keep XML concise; use meaningful variable names; test conditions thoroughly. Security and Vulnerability Notes -------------------------------- [](#security-and-vulnerability-notes) - **Resolved Vulnerabilities**: - **Connector Errors**: Previously unhandled missing connectors now throw `EngineException`, preventing silent failures. - **Parsing Issues**: XML parsing uses `libxml_use_internal_errors(true)` to suppress warnings and throws `ParserException` on invalid structure, mitigating XML injection risks. - **Tool Invocation**: Parameters are resolved but not executed as code; use strict types in tools to avoid type errors. - **Corrected Inefficiencies**: - **Parsing Optimization**: SimpleXML is lightweight; no recursive parsing depth issues. Variable extraction is top-level only for speed. - **Condition Evaluation**: Regex-based for simple ops, avoiding full expression parsers; no infinite loops as branches are linear. - **Security Considerations**: - **Input Validation**: POML XML should be trusted or sanitized externally; `resolve()` in StateManager replaces `{{var}}` but doesn't execute code—extend with filters if needed. - **API Keys**: Never commit keys; use `.env` files (add to `.gitignore`). - **JSON Handling**: `json_decode` with error checks prevents malformed response crashes. - **Recommendations**: Run in isolated environments for untrusted POML; audit tools for side effects; use HTTPS for `HttpConnector`. For contributions or issues, please refer to the code structure in `src/`. ### Health Score 16 — LowBetter than 5% of packages Maintenance43 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity13 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/5c84b643bae0caee282cb5cb88c300aab800afbed904c459e9fcad4e493a3850?d=identicon)[kuasarx](/maintainers/kuasarx) --- Top Contributors [![kuasarx](https://avatars.githubusercontent.com/u/34275535?v=4)](https://github.com/kuasarx "kuasarx (2 commits)") ### Embed Badge ![Health badge](/badges/poml-toolkit/health.svg) ``` [![Health](https://phpackages.com/badges/poml-toolkit/health.svg)](https://phpackages.com/packages/poml-toolkit) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)