papi-ai / papi-core
PHP AI Agents Workflow Automation - Core Library
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
- ext-openssl: *
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^3.7
This package is not auto-updated.
Last update: 2025-07-07 07:35:31 UTC
README
Papi Core is the decoupled PHP library powering papi-ai, an open-source, n8n-inspired AI workflow automation platform.
Build powerful AI-powered workflows with a modern, extensible PHP engine that supports AI agents, custom tools, and seamless integrations.
โจ Features
- ๐ค AI Agent Support: Integrate LLMs (OpenAI, Anthropic) with tool-calling capabilities
- ๐ง Extensible Tool System: Create custom tools for AI agents to use
- ๐ Integration Framework: Build nodes for external services and APIs
- โก Modern Workflow Engine: Compose, execute, and extend workflows with nodes and connections
- ๐๏ธ Framework Agnostic: Use standalone or with Laravel/Symfony bundles
- ๐งช Testing Ready: Comprehensive testing utilities and mock clients
๐ Quick Start
Requirements
- PHP 8.1 or higher
- Composer
- OpenAI API key (for AI features)
Installation
composer require papi-ai/papi-core
Basic Workflow Example
<?php use Papi\Core\Workflow; use Papi\Core\Connection; use Papi\Core\Agents\AIAgent; use Papi\Core\Tools\HttpTool; use Papi\Core\Tools\MathTool; use Papi\Core\Integrations\OpenAIClient; // Create tools for the AI agent $httpTool = new HttpTool(); $mathTool = new MathTool(); // Create AI agent with tools $aiAgent = new AIAgent('assistant', 'AI Assistant'); $aiAgent->setModel('gpt-3.5-turbo') ->setSystemPrompt('You are a helpful assistant that can fetch data and perform calculations.') ->addTool($httpTool) ->addTool($mathTool); // Create workflow $workflow = new Workflow('demo_workflow'); $workflow->addNode($aiAgent); // Execute workflow $execution = $workflow->execute([ 'query' => 'What is the square root of 144?' ]); echo json_encode($execution->getOutputData(), JSON_PRETTY_PRINT);
AI Agent with HTTP Integration
<?php use Papi\Core\Workflow; use Papi\Core\Connection; use Papi\Core\Integrations\Http\HttpNode; use Papi\Core\Integrations\Process\ProcessNode; // Create HTTP node to fetch data $httpNode = new HttpNode('fetch', 'Fetch Data'); $httpNode->setConfig([ 'method' => 'GET', 'url' => 'https://jsonplaceholder.typicode.com/posts/1', ]); // Create process node to transform data $processNode = new ProcessNode('process', 'Process Data'); $processNode->setConfig([ 'operations' => [ 'extract_title' => 'data.title', 'extract_body' => 'data.body', ] ]); // Create workflow $workflow = new Workflow('data_workflow'); $workflow->addNode($httpNode); $workflow->addNode($processNode); $workflow->addConnection(new Connection('fetch', 'process')); // Execute workflow $execution = $workflow->execute(); $result = $execution->getOutputData();
๐ ๏ธ Creating Custom Tools
Tools are functions that AI agents can call to perform specific tasks. Here's how to create a custom tool:
<?php use Papi\Core\Tools\ToolInterface; class WeatherTool implements ToolInterface { public function getName(): string { return 'get_weather'; } public function getDescription(): string { return 'Get current weather information for a location'; } public function getParameters(): array { return [ 'location' => [ 'type' => 'string', 'description' => 'City name or coordinates', 'required' => true ], 'units' => [ 'type' => 'string', 'description' => 'Temperature units (celsius/fahrenheit)', 'default' => 'celsius' ] ]; } public function execute(array $params): array { $location = $params['location']; $units = $params['units'] ?? 'celsius'; // Your weather API logic here $weather = $this->fetchWeather($location, $units); return [ 'location' => $location, 'temperature' => $weather['temp'], 'conditions' => $weather['conditions'], 'units' => $units ]; } public function validate(array $params): bool { return isset($params['location']) && !empty($params['location']); } } // Use the custom tool $weatherTool = new WeatherTool(); $aiAgent->addTool($weatherTool);
๐ Creating Custom Integrations
Integrations are workflow nodes that connect to external services. Here's how to create a custom integration:
<?php use Papi\Core\Node; class SlackNode extends Node { public function execute(array $input): array { $config = $this->config; $webhookUrl = $config['webhook_url'] ?? ''; $message = $input['message'] ?? $config['message'] ?? ''; if (empty($webhookUrl) || empty($message)) { throw new \InvalidArgumentException('Webhook URL and message are required'); } // Send message to Slack $response = $this->sendToSlack($webhookUrl, $message); return [ 'status' => 'success', 'data' => $response, 'message_sent' => $message ]; } private function sendToSlack(string $webhookUrl, string $message): array { // Slack webhook implementation $payload = ['text' => $message]; $ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => $webhookUrl, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true, ]); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); return [ 'status_code' => $httpCode, 'response' => $response ]; } } // Use the custom integration $slackNode = new SlackNode('notify', 'Slack Notification'); $slackNode->setConfig(['webhook_url' => 'https://hooks.slack.com/...']); $workflow->addNode($slackNode);
๐ Documentation
๐ Documentation Index - Complete documentation overview and navigation
Getting Started:
- Getting Started - Installation and basic usage
- Workflow Patterns - Understanding workflow design
- AI Agents - Working with AI agents and tools
Development:
- Integrations - Available integrations and creating custom ones
- Developer Guide - Creating custom tools, integrations, and testing
- Templates - Reusable workflow patterns
Reference & Support:
- API Reference - Complete API documentation
- Troubleshooting - Common issues and debugging techniques
๐๏ธ Architecture
Core Components
- Workflow: Main container for workflow logic and execution
- Node: Individual processing units (AI agents, integrations, etc.)
- Connection: Links between nodes with data transformation
- Execution: Workflow execution engine with error handling
- Tools: Functions that AI agents can call
- Integrations: External service connectors
Workflow Execution
// Create workflow $workflow = new Workflow('my_workflow'); // Add nodes $workflow->addNode($node1); $workflow->addNode($node2); // Connect nodes $workflow->addConnection(new Connection('node1', 'node2')); // Execute with input data $execution = $workflow->execute(['input' => 'data']); // Get results $output = $execution->getOutputData(); $nodeResults = $execution->getNodeResults();
๐งช Testing
Papi Core includes comprehensive testing utilities:
<?php use Papi\Core\Integrations\MockOpenAIClient; // Use mock client for testing $mockClient = new MockOpenAIClient(); $aiAgent->setOpenAIClient($mockClient); // Test workflow execution $execution = $workflow->execute(['test' => 'data']); $this->assertEquals('success', $execution->getStatus());
๐ง Roadmap
Current Features
- โ Core workflow engine
- โ AI agent support with tool-calling
- โ HTTP and Math tools
- โ Basic integrations (HTTP, Process, Output)
- โ Mock OpenAI client for testing
Planned Features
- ๐ Parallel workflow execution
- ๐ Conditional workflow logic
- ๐ Loop workflows
- ๐ Plugin discovery system
- ๐ More built-in integrations (Slack, Discord, databases)
- ๐ Workflow templates and sharing
- ๐ Advanced AI agent features (memory, context)
๐ค Community & Support
Ecosystem Projects
Papi Core is part of the larger papi-ai ecosystem:
- papi-ui - Laravel-based web interface
- papi-symfony-bundle - Symfony integration
- papi-plugins - Community plugins
- papi-website - Documentation and landing page
Getting Help
- ๐ Documentation - Comprehensive guides and API reference
- ๐ Issues - Report bugs and request features
- ๐ฌ Discussions - Ask questions and share ideas
Contributing
We welcome contributions! Please see our Contributing Guide for details.
- ๐ Bug reports and feature requests
- ๐ป Code contributions and pull requests
- ๐ Documentation improvements
- ๐งช Test coverage additions
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
- Inspired by n8n workflow automation
- Built with modern PHP practices and standards
- Community-driven development and feedback