laravel-cortex/cortex

Zero-Config Enterprise Agent for Laravel

dev-main 2025-12-20 18:33 UTC

Requires

• php: ^8.2
• illuminate/support: *
• livewire/livewire: ^3.0
• openai-php/client: ^0.10.3

MIT

• Antigravity

README

The missing brain for your Laravel application.
Give your users a powerful "Cmd+K" interface to navigate, search, and execute complex actions using natural language.

✨ Features at a Glance

Feature	Description
🔍 Global Smart Search	Instantly find any Route, Model, or Resource in your app.
🤖 AI Natural Language	Type "Delete inactive users" or "Show high value orders" and let AI handle it.
🏢 Multi-Tenant Switcher	Switch organizations instantly without complex UI. Built-in session handling.
⚡ Stack Agnostic	Drop-in support for Livewire, Vanilla JS (Blade), and Headless (Next.js).
🛡️ Permission Aware	Automatically hides actions user isn't authorized for (can, auth middleware).
⚙️ Developer Mode	Toggle between client (friendly) and developer (debug/system) modes.

🚀 Installation

1. Require the Package

composer require laravel-cortex/cortex

2. Run the Installer

This interactive command helps you choose your stack and publishes necessary assets.

php artisan cortex:install

3. Add to Layout

Depending on your stack, add the standard component or script.

🟢 Livewire (TALL Stack)

Add this to your main layout (e.g., layouts/app.blade.php) before the closing </body> tag:

<livewire:cortex-palette />

� Blade (Vanilla JS)

For traditional Laravel apps without Livewire:

<script src="{{ asset('vendor/cortex/js/cortex.js') }}"></script>

🔵 API (Next.js / React / Vue)

Cortex exposes a REST API for headless apps.

• GET /api/cortex/search?query=...
• POST /api/cortex/execute

🎮 Usage

Press Cmd+K (Mac) or Ctrl+K (Windows) to open the palette.

1. Navigation & Search

Just start typing. Cortex indexes all your named routes automatically via the cortex:index command.

• Type "Users" → Finds UserController@index.
• Type "Settings" → Finds ProfileController@edit.

2. AI Commands (The Magic 🪄)

If enabled, Cortex sends sentence-length queries (> 3 words) to OpenAI/Gemini.

• "Delete students named John"
• "Create a new product called 'Super Widget'"
• "Switch to Acme Corp"

How it works:

1. Intent Recognition: AI determines if you want to View, Create, or Delete.
2. Safety Check: For destructive actions, Cortex calculates the impact (e.g., "5 records found") and asks for confirmation.
3. Execution: Runs the action securely.

3. Multi-Tenant Switching

Cortex can search your Tenant model (e.g., Organization).

1. Type the name of the tenant (e.g., "Google").
2. Press Enter to switch context.
3. The Session key current_tenant_id is updated automatically.

⚙️ Configuration & Environment

Control Cortex behavior via your .env file.

Variable	Default	Description
CORTEX_AI_ENABLED	true	Enable/Disable Natural Language interaction.
CORTEX_AI_DRIVER	openai	AI Provider (openai, gemini).
OPENAI_API_KEY	null	Your LLM API Key.
CORTEX_TENANTS_ENABLED	false	Enable the Organization switcher.
CORTEX_TENANT_MODEL	App\Models\Organization	The model class for your tenants.
CORTEX_MODE	client	Crucial Setting (See below).
CORTEX_STACK	livewire	Controls which assets invoke the runner (livewire, blade, api).

🛠️ Developer vs Client Mode (CORTEX_MODE)

• client (Default):
  • Hides technical system routes.
  • Shows user-friendly descriptions ("View Profile" instead of profile.edit).
  • Hides "Dangerous" system commands (Clear Cache, etc).
• developer:
  • Shows exact Route URIs (/users/{id}/edit).
  • Enables System Actions like optimize:clear, route:list.
  • Great for admins and developers debugging the app.

🛡️ Security & Permissions

Cortex is secure by default. It respects your application's existing authorization gates.

1. Middleware Check: Routes with middleware('can:manage-users') are hidden from users without that permission.
2. Policy Check: It checks Gate::allows() against route actions automatically.
3. Authentication: Guest users only see Public routes (e.g., Login, Register). Authenticated users see what their role allows.

Note for API Users: When using the API (/api/cortex/search), ensure you send the request with an Authenticated Session (cookies) or Bearer Token. Unauthenticated requests will be treated as "Guest".

� Advanced Customization

Publish the configuration file to define custom actions and searchable models.

php artisan vendor:publish --tag=cortex-config

Defining Searchable Models

In config/cortex.php:

'models' => [
    'product' => [
        'class' => 'App\Models\Product',
        'searchable' => ['name', 'sku'],
        'actions' => [
            'view' => 'products.show',
            'edit' => 'products.edit',
        ]
    ]
]

🤝 Contributing

We love contributions! Please submit Pull Requests to the GitHub repository.

📄 License

The MIT License (MIT). Please see License File for more information.