PHPackages bmadigan/overpass - 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. bmadigan/overpass ActiveLibrary[Utility & Helpers](/categories/utility) bmadigan/overpass ================= A robust Laravel package for integrating Python AI capabilities through a secure subprocess bridge v1.0.0(8mo ago)31651MITPHPPHP ^8.2CI passing Since Aug 27Pushed 5mo ago1 watchersCompare [ Source](https://github.com/bmadigan/overpass)[ Packagist](https://packagist.org/packages/bmadigan/overpass)[ Docs](https://github.com/bmadigan/overpass)[ RSS](/packages/bmadigan-overpass/feed)WikiDiscussions main Synced today READMEChangelogDependencies (13)Versions (4)Used By (0) Overpass ======== [](#overpass) [![Latest Version on Packagist](https://camo.githubusercontent.com/349d069fbcc2e1be117c567603a890518201e5f8fd9b069e570a5c0c556d11c8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626d61646967616e2f6f766572706173732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bmadigan/overpass)[![Total Downloads](https://camo.githubusercontent.com/6076a8e181bd2f90f52d8e898c6561019d272ae6d668650c202a8aaaa2b75f79/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626d61646967616e2f6f766572706173732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bmadigan/overpass) A robust Laravel package for integrating Python AI capabilities through a secure subprocess bridge. Instead of reimplementing complex AI libraries in PHP, this package provides a clean interface to delegate AI operations to Python's rich ecosystem (OpenAI, LangChain, scikit-learn, etc.). ๐ŸŽฌ Demo Application ------------------ [](#-demo-application) Check out **[Ask-My-Doc](https://github.com/bmadigan/ask-my-doc)** - a sophisticated document Q&A system built with Overpass that showcases real-world AI integration: [![Ask-My-Doc Demo](https://github.com/bmadigan/ask-my-doc/raw/main/public/screenshot.png)](https://github.com/bmadigan/ask-my-doc) **Ask-My-Doc** demonstrates Overpass in action with: - ๐Ÿ“„ Document ingestion and intelligent chunking - ๐Ÿ” Semantic search using OpenAI embeddings - ๐Ÿ’ฌ AI-powered Q&A with source citations - โšก Real-time Python bridge status monitoring - ๐ŸŽจ Beautiful dark-themed UI inspired by Linear > **Note**: This package is **not affiliated** with the existing [decodelabs/overpass](https://github.com/decodelabs/overpass) package, which provides a PHP bridge to Node.js. Our "Overpass" package serves a different purpose - bridging between PHP and Python for AI operations. ๐Ÿš€ Features ---------- [](#-features) - **๐Ÿ Python Integration**: Seamlessly execute Python AI scripts from Laravel - **๐Ÿ”’ Secure**: API keys passed via environment variables, never in command lines - **โšก Async Ready**: Built for Laravel queues and background processing - **๐Ÿ›ก๏ธ Robust Error Handling**: Graceful degradation and comprehensive logging - **๐Ÿงช Production Tested**: Battle-tested patterns for reliability - **๐ŸŽฏ Laravel Native**: Follows Laravel conventions with facades, service providers, and Artisan commands ๐Ÿ“ฆ Installation -------------- [](#-installation) You can install the package via composer: ``` composer require bmadigan/overpass ``` Install the package with example Python scripts: ``` php artisan overpass:install --with-examples ``` Publish the config file: ``` php artisan vendor:publish --tag="overpass-config" ``` โš™๏ธ Configuration ---------------- [](#๏ธ-configuration) Add your OpenAI API key to your `.env` file: ``` OPENAI_API_KEY=your-openai-api-key OVERPASS_SCRIPT_PATH=/path/to/your/python/script.py ``` Configure the package in `config/overpass.php`: ``` return [ 'script_path' => env('OVERPASS_SCRIPT_PATH', base_path('overpass-ai/main.py')), 'timeout' => env('OVERPASS_TIMEOUT', 90), 'max_output_length' => env('OVERPASS_MAX_OUTPUT', 10000), // ... more options ]; ``` ๐ŸŽฏ Usage ------- [](#-usage) ### Basic Usage [](#basic-usage) ``` use Bmadigan\Overpass\Facades\Overpass; // Test the connection $healthCheck = Overpass::testConnection(); // Generate embeddings $embedding = Overpass::generateEmbedding('Hello, world!'); // Execute custom operations $result = Overpass::execute('custom_operation', ['data' => 'value']); ``` ### Chat Operations [](#chat-operations) ``` $response = Overpass::chat([ 'message' => 'What is machine learning?', 'session_id' => 'user-123', 'context' => ['previous' => 'conversation'] ]); echo $response['response']; // AI-generated response ``` ### Vector Search [](#vector-search) ``` $results = Overpass::vectorSearch('machine learning concepts', [ 'limit' => 10, 'threshold' => 0.8 ]); ``` ### Queue Integration [](#queue-integration) ``` use Bmadigan\Overpass\Services\PythonAiBridge; // In a Laravel job class ProcessAiTask implements ShouldQueue { public function handle(PythonAiBridge $bridge) { $result = $bridge->analyzeData($this->data); // Process result... } } ``` ๐Ÿ Python Script Structure ------------------------- [](#-python-script-structure) Your Python script should follow this pattern: ``` import sys import json def health_check(data): return { 'success': True, 'data': {'status': 'healthy'} } def analyze_data(data): # Your AI logic here return { 'success': True, 'data': {'result': 'analysis complete'} } def main(): operation = sys.argv[1] data = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {} operations = { 'health_check': health_check, 'analyze_data': analyze_data, } if operation in operations: result = operations[operation](data) print(json.dumps(result)) else: print(json.dumps({'success': False, 'error': 'Unknown operation'})) if __name__ == '__main__': main() ``` ๐Ÿงช Testing --------- [](#-testing) ``` # Test the bridge connection php artisan overpass:test # Run package tests composer test # Run tests with coverage composer test-coverage ``` ๐Ÿ“š Advanced Usage ---------------- [](#-advanced-usage) ### Custom Operations [](#custom-operations) ``` // Define custom operations in your Python script $result = Overpass::execute('sentiment_analysis', [ 'text' => 'This product is amazing!', 'options' => ['return_confidence' => true] ]); ``` ### Error Handling [](#error-handling) ``` try { $result = Overpass::generateEmbedding($text); } catch (\Exception $e) { Log::error('Embedding generation failed', ['error' => $e->getMessage()]); // Implement fallback logic } ``` ### Dependency Injection [](#dependency-injection) ``` class MyService { public function __construct( private PythonAiBridge $bridge ) {} public function processData(array $data): array { return $this->bridge->execute('process', $data); } } ``` ๐Ÿ”ง Artisan Commands ------------------ [](#-artisan-commands) ``` # Install and setup the package php artisan overpass:install --with-examples # Test the bridge connection php artisan overpass:test --verbose # Check configuration php artisan overpass:test --timeout=60 ``` ๐Ÿšจ Troubleshooting ----------------- [](#-troubleshooting) **Connection Failures:** - Ensure Python 3 is installed and accessible - Check that your Python script path is correct - Verify Python dependencies are installed - Test your OpenAI API key **Performance Issues:** - Increase timeout for complex operations - Use Laravel queues for long-running tasks - Consider output length limits **Memory Issues:** - Set appropriate `max_output_length` in config - Use streaming for large datasets - Monitor Python process memory usage ๐Ÿ“Š Performance Considerations ---------------------------- [](#-performance-considerations) - **Timeouts**: Set appropriate timeouts based on operation complexity - **Memory**: Monitor both PHP and Python memory usage - **Queues**: Use Laravel queues for expensive AI operations - **Caching**: Cache embedding results and AI responses when appropriate ๐Ÿ”’ Security ---------- [](#-security) - API keys are passed via environment variables, never command line arguments - All input data is JSON-encoded to prevent injection attacks - Process isolation ensures Python failures don't crash Laravel - Comprehensive logging for audit trails ๐Ÿค Contributing -------------- [](#-contributing) Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ๐Ÿ› Security Vulnerabilities -------------------------- [](#-security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. ๐Ÿ“„ Credits --------- [](#-credits) - [Your Name](https://github.com/your-username) - [All Contributors](../../contributors) ๐Ÿ“œ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 38 โ€” LowBetter than 83% of packages Maintenance66 Regular maintenance activity Popularity15 Limited adoption so far Community8 Small or concentrated contributor base Maturity51 Maturing project, gaining track record 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. ### Release Activity Cadence Every ~53 days Total 2 Last Release 256d ago Major Versions 0.7.0 โ†’ v1.0.02025-10-20 ### Community Maintainers ![](https://www.gravatar.com/avatar/373edb9f38f75cc313d1418128340405488d14881ff12dfafa7022b8ea90147d?d=identicon)[bmadigan71](/maintainers/bmadigan71) --- Top Contributors [![bmadigan](https://avatars.githubusercontent.com/u/13608?v=4)](https://github.com/bmadigan "bmadigan (17 commits)") --- Tags laravelaivectoropenaipythonBridgemachine learningembeddinglangchainoverpasssubprocess ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/bmadigan-overpass/health.svg) ``` [![Health](https://phpackages.com/badges/bmadigan-overpass/health.svg)](https://phpackages.com/packages/bmadigan-overpass) ``` ### Alternatives [spatie/laravel-health Monitor the health of a Laravel application 87512.0M165](/packages/spatie-laravel-health)[spatie/laravel-pdf Create PDFs in Laravel apps 1.0k4.8M47](/packages/spatie-laravel-pdf)[codewithdennis/filament-select-tree The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths. 329530.5k29](/packages/codewithdennis-filament-select-tree)[worksome/exchange Check Exchange Rates for any currency in Laravel. 124603.0k](/packages/worksome-exchange)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.6k](/packages/rawilk-profile-filament-plugin)[finller/laravel-media A flexible media library for Laravel 472.1k](/packages/finller-laravel-media) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)