PHPackages lablnet/hyperflow-php - 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. [Framework](/categories/framework) 4. / 5. lablnet/hyperflow-php ActiveLibrary[Framework](/categories/framework) lablnet/hyperflow-php ===================== HyperFlow PHP port: Framework for building agents that rewrite and test their own improvements. 20[1 PRs](https://github.com/lablnet/hyperflow-php/pulls)JavaScriptCI failing Since Apr 29Pushed 4w agoCompare [ Source](https://github.com/lablnet/hyperflow-php)[ Packagist](https://packagist.org/packages/lablnet/hyperflow-php)[ RSS](/packages/lablnet-hyperflow-php/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependenciesVersions (2)Used By (0) HyperFlow (PHP) =============== [](#hyperflow-php) [![HyperFlow Logo](./assets/logo.png)](./assets/logo.png) HyperFlow PHP is a fully functional PHP port of the framework for building agents that rewrite and test their own improvements. Instead of manually retuning prompts and logic after every failure, HyperFlow runs a self-improvement loop where an agent evaluates what happened, edits its own code, tools, and prompts, then tests the new version in a sandbox. The core idea is simple: do not just rerun the same workflow. Learn from execution and get better over time. Built natively in PHP 8.1+ utilizing `openai-php/client`. Inspired by [HyperAgents](https://github.com/facebookresearch/HyperAgents) (Meta Research, 2026). > **⚠️ EXPERIMENTAL**: This project is currently in an experimental phase and is **not recommended for production use**. What it does ------------ [](#what-it-does) HyperFlow runs an evolutionary self-improvement loop with two roles: - **TaskAgent** solves the domain problem - **MetaAgent** studies evaluation results and improves the system Each generation: 1. Select a parent generation from the archive 2. MetaAgent reads past evaluation scores and edits the source code 3. Evaluation scripts run in a sandbox to score the new agent 4. Better agents are added back to the archive for future generations It is **self-referential**: the mechanism that improves the agent is itself part of the editable code. Important This framework is currently in an **Experimental** state. See [Limitations](docs_site/docs/guide/limitations.md) for more information. The TaskAgent gets better over generations without manual intervention. Installation ------------ [](#installation) Install using Composer: ``` composer require lablnet/hyperflow-php ``` Or install from source for development: ``` git clone https://github.com/lablnet/hyperflow-php.git cd hyperflow-php composer install ``` ### Requirements [](#requirements) - PHP 8.1+ - Composer - At least one LLM provider API key (e.g. `OPENAI_API_KEY`) Quick Start ----------- [](#quick-start) ``` # Set your API key in .env or export it cp .env.example .env # Edit .env and set OPENAI_API_KEY # Run the bash example cd examples/bash php run.php ``` Project Structure ----------------- [](#project-structure) ``` php/ composer.json src/ Agent/ AgentOptions.php # DTO for agent configuration AgentSystem.php # Abstract AgentSystem base class Llm.php # OpenAI client integration LlmConfig.php # Config DTO for the LLM LlmWithTools.php # Synchronous ReAct chat loop MetaAgent.php # MetaAgent (mutation operator) TaskAgent.php # TaskAgent (task solver) ToolRegistry.php # Tool registration Contracts/ BaseChatModel.php # LLM invocation interface BaseTool.php # Abstract class defining tools Message.php # Base Message class AIMessage.php # Assistant message model HumanMessage.php # User message model SystemMessage.php # System message model ToolMessage.php # Tool execution result model Core/ GenerateLoop.php # Main evolutionary loop Domains/ Base.php # Domain interfaces Harness.php # Evaluation harness Tools/ BashTool.php # Bash shell tool EditorTool.php # File editor tool Utils/ Archive.php # JSONL archive CRUD examples/ bash/ # Bash command generation calculator/ # Buggy tool fix demo factcheck/ # True/false classification ``` Supported Models ---------------- [](#supported-models) Since this PHP implementation relies primarily on the OpenAI API standard, you can pass any supported model string during configuration: ``` use HyperFlow\Agent\AgentOptions; $options = new AgentOptions(model: 'gpt-4o'); // 'gpt-4o', 'gpt-4o-mini', 'o3', etc. ``` Environment Variables --------------------- [](#environment-variables) The framework supports loading environment variables from a `.env` file in the project root. VariableDescription`OPENAI_API_KEY`OpenAI API keyExamples -------- [](#examples) ### Single Evaluation / Self-Improvement Loops [](#single-evaluation--self-improvement-loops) Execute the specific scripts depending on the example you want to run. The examples demonstrate both strict execution and evolutionary loops. ``` cd examples/bash && php run.php cd examples/factcheck && php run.php cd examples/paper_review && php run.php cd examples/calculator && php run.php ``` License ------- [](#license) MIT Citation -------- [](#citation) If you use this framework in your research, please cite the original HyperAgents paper: ``` @misc{zhang2026hyperagents, title={Hyperagents}, author={Jenny Zhang and Bingchen Zhao and Wannan Yang and Jakob Foerster and Jeff Clune and Minqi Jiang and Sam Devlin and Tatiana Shavrina}, year={2026}, eprint={2603.19461}, archivePrefix={arXiv}, primaryClass={cs.AI}, url={https://arxiv.org/abs/2603.19461}, } ``` ### Health Score 21 — LowBetter than 18% of packages Maintenance61 Regular maintenance activity Popularity3 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/aaa321ed1bec9048a01ab2d3adcfca294a6382180fcce5fd98ddd97f52814d3c?d=identicon)[lablnet](/maintainers/lablnet) --- Top Contributors [![lablnet](https://avatars.githubusercontent.com/u/27757785?v=4)](https://github.com/lablnet "lablnet (11 commits)") --- Tags agentaiclaudeframeworkharnesshyperflowopenaiopenclaw ### Embed Badge ![Health badge](/badges/lablnet-hyperflow-php/health.svg) ``` [![Health](https://phpackages.com/badges/lablnet-hyperflow-php/health.svg)](https://phpackages.com/packages/lablnet-hyperflow-php) ``` ### Alternatives [laravel/socialite Laravel wrapper around OAuth 1 & OAuth 2 libraries. 5.7k104.3M822](/packages/laravel-socialite)[laravel/dusk Laravel Dusk provides simple end-to-end testing and browser automation. 1.9k38.6M289](/packages/laravel-dusk)[pinguo/php-msf Pinguo Micro Service Framework For PHP 1.7k4.2k](/packages/pinguo-php-msf)[nineinchnick/edatatables Grid widget for the Yii Framework, wrapper for the DataTables jQuery plugin 173.2k](/packages/nineinchnick-edatatables) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)