laranail/polyglot

laranail/polyglot is not published to Packagist, so there is no registry-version badge to show: see Install.

A Python bridge for Laravel — call FastAPI/Flask services over HTTP, run scripts in a virtualenv behind a hardened process clamp, and receive HMAC-signed callbacks when long work finishes.

Requires PHP ^8.4.1 || ^8.5 on Laravel ^13.

Install

composer require laranail/polyglot
php artisan laranail::polyglot.install

Quick start guide and usage

Getting started

1. php artisan laranail::polyglot.install (see Install) publishes the config and prints what is left.

2. Point a service at its URL in .env. The default service is fastapi:

   POLYGLOT_FASTAPI_URL=http://127.0.0.1:8000

3. Only HTTP services are on by default. Local scripts stay off until POLYGLOT_PROCESS_ENABLED=true (it is code execution), and callbacks stay off until POLYGLOT_CALLBACKS_ENABLED=true and POLYGLOT_CALLBACK_SECRET is set.

Usage

use Simtabi\Laranail\Polyglot\Facades\Polyglot;

// A configured HTTP client — Laravel's own, so attach(), sink() and streaming work.
$vector = Polyglot::service('fastapi')->post('/embed', ['text' => $text])->json('vector');

// Or the transport-agnostic call, which returns a result rather than throwing.
$result = Polyglot::run('fastapi:embed', ['text' => $text]);
$result->ok ? $result->get('vector') : report($result->message);

// A local script, from an allow-list. Payload on stdin, JSON back.
$result = Polyglot::run('embed', ['text' => $text]);

// Work too slow for a request: submit, and be called back.
$handle = Polyglot::submit('fastapi:train', ['epochs' => 50], route('python.done'));

php artisan laranail::polyglot.doctor   # every service, its TLS mode, auth, and a live probe

Documentation

Hosted at opensource.simtabi.com/documentation/laranail/polyglot.

Guides

• Installation — requirements, what to publish, what stays off
• Getting started — the two transports and the first calls
• Configuration — every key and its environment variable
• Security — the threat model and every guard, with the reasoning
• Architecture — the transports, the resolver, and what the rename changed
• Release — cutting a version

Reference

• The HTTP transport — the service registry, auth, TLS, health
• The process transport — runtimes, the allow-list, the clamps
• Results and errors — CallResult, the eight error codes, redaction
• Signed callbacks — HMAC, the timestamp window, the replay guard
• Commands — doctor, health, run, install, make-service

Recipes

• Call an HTTP service
• Add a runtime

Security

This package executes local processes and can expose an unauthenticated HTTP endpoint, so both are off until you turn them on, and the reasoning behind every guard is written down in docs/security.md. The short version:

• Scripts are named from an allow-list; a caller cannot express a path at all.
• Commands are arrays, never strings, so nothing reaches a shell.
• Payloads travel on stdin, never argv — /proc/<pid>/cmdline is world-readable.
• The child gets an allow-listed environment, not yours.
• Callbacks need a valid HMAC over the raw body, a fresh timestamp, and an unused delivery id. A timestamp window alone does not stop replay.

Report vulnerabilities per SECURITY.md (opensource@simtabi.com).

Contributing & security

Issues and PRs are welcome — see CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.

License

MIT © Simtabi LLC. See LICENSE.