zerocool/intent-workbench

IntentWorkbench Laravel package — local execution, cloud parsing (Nightwatch-style)

1.1.0 2026-06-03 19:28 UTC

Requires

• php: ^8.3
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• laravel/framework: ^11.0|^12.0|^13.0
• maatwebsite/excel: ^3.1
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^12.0

MIT

• Noé Francisco Martínez Merino
• ZeroCool Network

• laravel
• ai
• orchestration
• intent

README

Laravel package for IntentWorkbench — natural language to structured business actions. Parse in cloud. Execute in Laravel.

What this package is / is not

Is:

• HTTP client to IntentWorkbench Cloud for NL parsing (BYOK AI keys live in the cloud portal)
• Local action registry and execution against your database
• Widget, PDF, Excel, and JSON output generators
• Table/column/relation mappings for brownfield schemas

Is not:

• A local NL parser — use IntentWorkbench::process(), not ::parse()
• A hosted ERP or data store (customer data never leaves your Laravel app)
• A replacement for cloud portal auth, billing, or tenant management

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13 (runtime illuminate/* constraints)
• IntentWorkbench Cloud account with API key (iw_ prefix) and tenant ID

The package test suite in this repo runs on Laravel 13 via Orchestra Testbench 11. Validate older Laravel versions in your app before production.

Install

Production (Packagist) — what composer require downloads:

composer require zerocool/intent-workbench:^1.0@beta
php artisan vendor:publish --tag=intent-workbench-config
php artisan intent-workbench:status

^1.0@beta tracks the latest Packagist beta (see RELEASE.md). If Packagist lags the monorepo, run composer run package:release-check and follow the tag push steps in RELEASE.md before telling customers to upgrade.

Monorepo development (path repository, local):

"repositories": [{ "type": "path", "url": "../../packages/laravel" }],
"require": { "zerocool/intent-workbench": "@dev" }

Copy tenant-specific values from cloud portal Settings → Integration.

Release alignment check (maintainers)

composer run package:release-check

Exits 0 only when packages/laravel/composer.json, GitLab mirror tag, and Packagist beta versions match.

Environment variables

Variable	Required	Description
INTENT_WORKBENCH_TOKEN	Yes	API key from cloud portal (iw_…)
INTENT_WORKBENCH_TENANT	Yes	Tenant slug sent as X-Tenant header
INTENT_WORKBENCH_ENABLED	Yes	Set false in PHPUnit to skip cloud HTTP
INTENT_WORKBENCH_API_URL	Yes	Cloud API base, e.g. https://intent-workbench.hifenix.com/api/v1
INTENT_WORKBENCH_OFFLINE	No	true uses FakeAiDriver for local dev without cloud

INTENT_WORKBENCH_TOKEN=iw_xxxxxxxx
INTENT_WORKBENCH_TENANT=acme-corp
INTENT_WORKBENCH_ENABLED=true
INTENT_WORKBENCH_API_URL=https://intent-workbench.hifenix.com/api/v1

Disable cloud in tests (Nightwatch pattern):

<env name="INTENT_WORKBENCH_ENABLED" value="false"/>

Quick start: IntentWorkbench::process()

use IntentWorkbench\Laravel\Facades\IntentWorkbench;

$result = IntentWorkbench::process('Show invoices from last month');
// $result['intent'] — parsed JSON from cloud
// $result['data']   — action output from your DB

Flow: package POSTs NL to cloud with X-API-Key + X-Tenant → cloud returns intent JSON → package resolves a registered action → queries your tables.

Direct POST /api/v1/intent on the portal may parse and execute against portal DB. Package integrators should always use IntentWorkbench::process(), which re-executes on the customer database.

Default actions (2)

Action key	Description
finance.invoices.report	Invoice report (widget, PDF, Excel, JSON)
sales.customers.report	Customer report

Both ship pre-registered in the service provider. Register additional actions with registerAction().

Output formats

Controlled by intent format or console/widget options:

Format	Output
widget	HTML table/card (default)
json	Structured array
pdf	Downloadable PDF
excel	Spreadsheet export

Register a custom action

// AppServiceProvider::boot()
use IntentWorkbench\Laravel\Facades\IntentWorkbench;

IntentWorkbench::registerAction(
    'operations.orders.report',
    \App\Actions\OrderReportAction::class,
);

Implement ActionInterface for your {domain}.{entity}.{action} key. Unregistered actions throw ActionNotAllowedException (deny-by-default).

Table mappings

Map logical entities to physical tables in config/intent-workbench.php:

'table_mappings' => [
    'finance' => [
        'invoices' => 'acct_sales_invoices',
    ],
],
'column_mappings' => [
    'finance.invoices' => [
        'date' => 'invoice_date',
        'amount' => 'total_amount',
    ],
],
'relation_mappings' => [
    'finance.invoices' => [
        'customer' => [
            'table' => 'crm_accounts',
            'foreign_key' => 'customer_id',
            'owner_key' => 'id',
        ],
    ],
],

See cloud portal /docs#schema-mapping for the three-layer model.

Console embed (Blade, Livewire, React)

1. Add a POST route that returns IntentWorkbench::console(...) (see examples/ in the package).
2. Blade: <x-intent-workbench::console :process-url="route('intent.process')" /> with csrf-token meta in layout.
3. Livewire: php artisan vendor:publish --tag=intent-workbench-examples — copies IntentConsole + view.
4. React/Inertia: publish ConsoleSlot.tsx or copy from examples/react/ConsoleSlot.tsx.

return IntentWorkbench::console($request->input('input'), $request->input('format', 'widget'), null, $request);
return IntentWorkbench::widget('Customer report');

Offline mode

INTENT_WORKBENCH_OFFLINE=true

Uses FakeAiDriver with predefined intents — suitable for demos; label UI "Simulated demo (offline driver)".

Artisan commands

Command	Purpose
php artisan intent-workbench:status	Verify token, tenant, and cloud connectivity
php artisan intent-workbench:registry-sync	Sync action registry metadata with cloud

Troubleshooting

Symptom	Fix
HTTP 401	Invalid or revoked token — create a new iw_ key in cloud portal
HTTP 403 / missing tenant	Set INTENT_WORKBENCH_TENANT to your tenant slug
No cloud calls	INTENT_WORKBENCH_ENABLED=false — set true outside tests
Wrong endpoint	INTENT_WORKBENCH_API_URL must end with /api/v1

HTTP API reference

OpenAPI and portal docs live at /docs and openapi-v1.yaml. Outbound package auth uses X-API-Key and X-Tenant headers only.

License

Proprietary — see LICENSE.md.