feat(ai): Phase 2 — chat assistant with tool-calling

Second phase of the AI feature. Users can now open a slide-in chat drawer from the SiteHeader and ask natural-language questions about their company's invoices, customers, payments, and expenses. The LLM invokes pre-defined read-only tool functions (scoped to the current company at execute time) to fetch data and synthesize answers. **Database** — new ai_conversations and ai_messages tables. Messages are stored in OpenAI's chat format so AiAssistantService serializes a conversation into an API request with zero translation. Columns: role, content, tool_call_id, tool_calls JSON, model, tokens_in, tokens_out. Conversations are scoped (company_id, user_id) — one user's chats are invisible to everyone else, even inside the same company. Foreign-key cascade deletes. **Tool infrastructure** — AiTool abstract base + AiToolRegistry singleton (registered in a new AiServiceProvider). The base class enforces the security rule: every tool's execute() receives companyId and userId as injected parameters; tools' JSON schemas NEVER include a company_id field. An LLM physically cannot pass a company_id and escape tenancy. Modules can register their own tools by resolving the registry from their own ServiceProvider::boot(). **Nine built-in tools**: search_invoices, get_invoice, search_customers, get_customer, list_recent_payments, list_overdue_invoices, get_company_stats (aggregates for named periods), search_items, list_expense_categories. All read-only; no mutations. Each returns JSON-encodable data the LLM can parse. **AiAssistantService orchestration loop** — the heart of Phase 2. Flow: persist user message → build payload from system prompt + recent history (40-message window) + new user message → call driver.chatCompletion with tools → if tool_calls, execute each one via the registry (with injected scope), persist tool result, loop → if plain text, persist and return. Hard cap at 5 iterations to prevent runaway LLMs. System prompt pins the assistant to this company's data and forbids mutation. **Controllers + policy + rate limit** — POST /api/v1/ai/chat runs the orchestration loop. GET/PATCH/DELETE /api/v1/ai/conversations for CRUD. AiConversationPolicy enforces user_id+company_id match on every action. A new 'ai' RateLimiter in RouteServiceProvider throttles to 30 req/min per (user, company). New 'use ai' Gate defined in AppServiceProvider returns true for any authenticated user — the per-company kill-switch still goes through AiConfigurationService::resolveForCompany. **Frontend** — new features/company/ai/ folder with a Pinia store (ai-chat.store.ts) holding drawer state, current conversation, messages, and loading flags. AiChatDrawer.vue is a slide-in panel teleported to <body>, mounted globally in CompanyLayout.vue when bootstrap reports ai.enabled && ai.chat_enabled. Sub-components: AiChatMessage (user bubbles vs assistant bubbles), AiChatMessageInput (Enter submits, Shift+Enter newline), AiChatConversationList (sidebar with 'new chat' button, rename, delete). A SparklesIcon button in SiteHeader toggles the drawer. **Driver test double** — tests use a ScriptedAiDriver registered via AiDriverFactory::register('scripted', ...) that returns pre-queued AiChatResponse objects. Feature tests cover: happy path (new conversation + message persistence), tool-call loop (multi-round-trip with search_invoices), runaway-loop cap, driver-throws path, ai_enabled=NO rejection, chat role disabled rejection, per-user conversation visibility, cross-user policy enforcement, cascade delete. 388 tests pass (was 372, +16 new). Pint clean. npm run build clean. Phase 3 (WYSIWYG text generation popup) is the remaining follow-up.
2026-07-16 22:05:20 +00:00 · 2026-04-12 08:00:00 +02:00
parent c7fab5d52f
commit e861fc1fc1
39 changed files with 2776 additions and 1 deletions
--- a/tests/Feature/Ai/AiChatFlowTest.php
+++ b/tests/Feature/Ai/AiChatFlowTest.php
@@ -0,0 +1,290 @@
+<?php
+
+use App\Models\AiConversation;
+use App\Models\AiMessage;
+use App\Models\User;
+use App\Services\AiConfigurationService;
+use App\Support\Ai\AiChatResponse;
+use App\Support\Ai\AiDriver;
+use App\Support\Ai\AiDriverFactory;
+use App\Support\Ai\AiException;
+use Illuminate\Support\Facades\Artisan;
+use Laravel\Sanctum\Sanctum;
+
+use function Pest\Laravel\getJson;
+use function Pest\Laravel\postJson;
+
+/**
+ * Test double for AiDriver that returns pre-queued responses from an array,
+ * so tests can script tool-call loops without hitting any real LLM API.
+ *
+ * Usage:
+ *   ScriptedAiDriver::setResponses([
+ *       new AiChatResponse(message: null, toolCalls: [...]),
+ *       new AiChatResponse(message: 'Final answer'),
+ *   ]);
+ */
+class ScriptedAiDriver extends AiDriver
+{
+    /** @var array<int, AiChatResponse> */
+    public static array $responses = [];
+
+    public static int $callCount = 0;
+
+    /** @var array<int, array<string, mixed>> */
+    public static array $lastMessages = [];
+
+    public static function reset(): void
+    {
+        self::$responses = [];
+        self::$callCount = 0;
+        self::$lastMessages = [];
+    }
+
+    /**
+     * @param  array<int, AiChatResponse>  $responses
+     */
+    public static function setResponses(array $responses): void
+    {
+        self::$responses = $responses;
+        self::$callCount = 0;
+    }
+
+    public function chatCompletion(
+        array $messages,
+        string $model,
+        array $tools = [],
+        array $options = [],
+    ): AiChatResponse {
+        self::$lastMessages = $messages;
+        $response = self::$responses[self::$callCount] ?? new AiChatResponse(message: 'Default test reply');
+        self::$callCount++;
+
+        return $response;
+    }
+
+    public function textCompletion(string $prompt, string $model, array $options = []): string
+    {
+        return 'text completion test';
+    }
+
+    public function validateConnection(): array
+    {
+        return ['ok' => true];
+    }
+}
+
+beforeEach(function () {
+    Artisan::call('db:seed', ['--class' => 'DatabaseSeeder', '--force' => true]);
+    Artisan::call('db:seed', ['--class' => 'DemoSeeder', '--force' => true]);
+
+    $this->user = User::find(1);
+    $this->companyId = $this->user->companies()->first()->id;
+
+    $this->withHeaders(['company' => $this->companyId]);
+    Sanctum::actingAs($this->user, ['*']);
+
+    // Enable AI globally so resolveForCompany returns a config
+    app(AiConfigurationService::class)->saveGlobalConfig([
+        'ai_enabled' => 'YES',
+        'ai_driver' => 'scripted',
+        'ai_api_key' => 'test-key',
+        'ai_chat_enabled' => 'YES',
+        'ai_chat_model' => 'test-model',
+    ]);
+
+    // Register the scripted driver so AiDriverFactory returns it for 'scripted'
+    AiDriverFactory::register('scripted', ScriptedAiDriver::class);
+    ScriptedAiDriver::reset();
+});
+
+afterEach(function () {
+    ScriptedAiDriver::reset();
+});
+
+test('chat endpoint creates a new conversation and persists user + assistant messages', function () {
+    ScriptedAiDriver::setResponses([
+        new AiChatResponse(message: 'Hello back!'),
+    ]);
+
+    $response = postJson('/api/v1/ai/chat', [
+        'message' => 'Hi assistant',
+    ])->assertOk();
+
+    $conversationId = $response->json('conversation.id');
+    expect($conversationId)->toBeInt();
+    expect($response->json('message.content'))->toBe('Hello back!');
+    expect($response->json('message.role'))->toBe('assistant');
+
+    // Both user and assistant messages should be persisted
+    $conversation = AiConversation::find($conversationId);
+    expect($conversation->user_id)->toBe($this->user->id);
+    expect($conversation->company_id)->toBe($this->companyId);
+
+    $messages = $conversation->messages()->orderBy('created_at')->get();
+    expect($messages->pluck('role')->all())->toBe(['user', 'assistant']);
+    expect($messages[0]->content)->toBe('Hi assistant');
+    expect($messages[1]->content)->toBe('Hello back!');
+});
+
+test('chat endpoint runs a tool-call loop and returns the final answer', function () {
+    // Round 1: LLM requests search_invoices
+    // Round 2: LLM produces final text
+    ScriptedAiDriver::setResponses([
+        new AiChatResponse(
+            message: null,
+            toolCalls: [[
+                'id' => 'call_1',
+                'name' => 'search_invoices',
+                'arguments' => ['limit' => 5],
+            ]],
+            finishReason: 'tool_calls',
+        ),
+        new AiChatResponse(message: 'Here are your invoices.'),
+    ]);
+
+    $response = postJson('/api/v1/ai/chat', [
+        'message' => 'Show me recent invoices',
+    ])->assertOk();
+
+    expect($response->json('message.content'))->toBe('Here are your invoices.');
+    expect(ScriptedAiDriver::$callCount)->toBe(2);
+
+    // Conversation should now contain: user, assistant(tool_calls), tool(result), assistant(final)
+    $conversation = AiConversation::find($response->json('conversation.id'));
+    $roles = $conversation->messages()->orderBy('id')->pluck('role')->all();
+    expect($roles)->toBe(['user', 'assistant', 'tool', 'assistant']);
+});
+
+test('chat endpoint caps runaway tool-call loops at MAX_TOOL_ITERATIONS', function () {
+    // All responses are tool_calls — simulating a model stuck in a loop
+    $loopResponse = new AiChatResponse(
+        message: null,
+        toolCalls: [[
+            'id' => 'call_loop',
+            'name' => 'search_invoices',
+            'arguments' => [],
+        ]],
+        finishReason: 'tool_calls',
+    );
+    // Queue 10 of them — way more than the 5-iteration cap
+    ScriptedAiDriver::setResponses(array_fill(0, 10, $loopResponse));
+
+    $response = postJson('/api/v1/ai/chat', [
+        'message' => 'Loop forever',
+    ])->assertOk();
+
+    // We should hit the cap and the service should return a graceful error message.
+    expect($response->json('message.content'))->toContain('tool-call budget');
+    // 5 calls + the "I give up" turn shouldn't exceed the hard cap
+    expect(ScriptedAiDriver::$callCount)->toBeLessThanOrEqual(5);
+});
+
+test('chat endpoint persists an error message when the driver throws', function () {
+    ScriptedAiDriver::setResponses([]);  // no responses queued → driver returns default
+
+    // Inject a failing driver via the factory
+    $failingDriver = new class('fake', []) extends AiDriver
+    {
+        public function chatCompletion(array $messages, string $model, array $tools = [], array $options = []): AiChatResponse
+        {
+            throw new AiException('test failure', 'server_error');
+        }
+
+        public function textCompletion(string $prompt, string $model, array $options = []): string
+        {
+            return '';
+        }
+
+        public function validateConnection(): array
+        {
+            return [];
+        }
+    };
+    AiDriverFactory::register('failing', $failingDriver::class);
+
+    app(AiConfigurationService::class)->saveGlobalConfig([
+        'ai_enabled' => 'YES',
+        'ai_driver' => 'failing',
+        'ai_api_key' => 'k',
+        'ai_chat_enabled' => 'YES',
+        'ai_chat_model' => 'test',
+    ]);
+
+    $response = postJson('/api/v1/ai/chat', [
+        'message' => 'Hello',
+    ])->assertOk();
+
+    expect($response->json('message.content'))->toContain('Error:');
+});
+
+test('chat endpoint rejects when AI is disabled for the company', function () {
+    app(AiConfigurationService::class)->saveGlobalConfig([
+        'ai_enabled' => 'NO',
+    ]);
+
+    postJson('/api/v1/ai/chat', [
+        'message' => 'Hi',
+    ])->assertStatus(422);
+});
+
+test('chat endpoint rejects when chat role is disabled even if AI is enabled', function () {
+    app(AiConfigurationService::class)->saveGlobalConfig([
+        'ai_enabled' => 'YES',
+        'ai_driver' => 'scripted',
+        'ai_api_key' => 'k',
+        'ai_chat_enabled' => 'NO',  // <— off
+        'ai_chat_model' => 'test',
+    ]);
+
+    postJson('/api/v1/ai/chat', [
+        'message' => 'Hi',
+    ])->assertStatus(422);
+});
+
+test('conversation index returns only the current user\'s conversations', function () {
+    // Create a conversation for the authenticated user
+    ScriptedAiDriver::setResponses([new AiChatResponse(message: 'hi')]);
+    postJson('/api/v1/ai/chat', ['message' => 'First message'])->assertOk();
+
+    // Create a conversation for a different user in the same company — should NOT be visible
+    $otherUser = User::factory()->create();
+    $otherUser->companies()->attach($this->companyId);
+    AiConversation::create([
+        'company_id' => $this->companyId,
+        'user_id' => $otherUser->id,
+        'title' => 'Other users secret chat',
+    ]);
+
+    $response = getJson('/api/v1/ai/conversations')->assertOk();
+
+    $titles = collect($response->json('conversations'))->pluck('title');
+    expect($titles)->not->toContain('Other users secret chat');
+});
+
+test('conversation show enforces ownership via policy', function () {
+    $otherUser = User::factory()->create();
+    $otherUser->companies()->attach($this->companyId);
+
+    $foreignConvo = AiConversation::create([
+        'company_id' => $this->companyId,
+        'user_id' => $otherUser->id,
+        'title' => 'Not yours',
+    ]);
+
+    getJson("/api/v1/ai/conversations/{$foreignConvo->id}")->assertForbidden();
+});
+
+test('conversation delete cascades messages', function () {
+    ScriptedAiDriver::setResponses([new AiChatResponse(message: 'reply')]);
+    $sendResponse = postJson('/api/v1/ai/chat', ['message' => 'First'])->assertOk();
+    $conversationId = $sendResponse->json('conversation.id');
+
+    // There should now be 2 messages
+    expect(AiMessage::where('conversation_id', $conversationId)->count())->toBe(2);
+
+    $this->deleteJson("/api/v1/ai/conversations/{$conversationId}")->assertOk();
+
+    expect(AiConversation::find($conversationId))->toBeNull();
+    expect(AiMessage::where('conversation_id', $conversationId)->count())->toBe(0);
+});
--- a/tests/Feature/Ai/Tools/SearchInvoicesToolTest.php
+++ b/tests/Feature/Ai/Tools/SearchInvoicesToolTest.php
@@ -0,0 +1,93 @@
+<?php
+
+use App\Models\Company;
+use App\Models\Customer;
+use App\Models\Invoice;
+use App\Services\Ai\Tools\SearchInvoicesTool;
+use Illuminate\Support\Facades\Artisan;
+
+beforeEach(function () {
+    Artisan::call('db:seed', ['--class' => 'DatabaseSeeder', '--force' => true]);
+    Artisan::call('db:seed', ['--class' => 'DemoSeeder', '--force' => true]);
+});
+
+test('search_invoices scopes strictly to the passed company id', function () {
+    $companyA = Company::first();
+    $companyB = Company::factory()->create();
+
+    $customerA = Customer::factory()->create(['company_id' => $companyA->id]);
+    $customerB = Customer::factory()->create(['company_id' => $companyB->id]);
+
+    $invoiceA = Invoice::factory()->create([
+        'company_id' => $companyA->id,
+        'customer_id' => $customerA->id,
+        'invoice_number' => 'AAA-001',
+    ]);
+    $invoiceB = Invoice::factory()->create([
+        'company_id' => $companyB->id,
+        'customer_id' => $customerB->id,
+        'invoice_number' => 'BBB-001',
+    ]);
+
+    $tool = new SearchInvoicesTool;
+
+    // Call with companyA — should ONLY see invoiceA
+    $resultA = $tool->execute([], $companyA->id, 1);
+    $numbersA = collect($resultA['invoices'])->pluck('invoice_number');
+    expect($numbersA)->toContain('AAA-001')->not->toContain('BBB-001');
+
+    // Call with companyB — should ONLY see invoiceB
+    $resultB = $tool->execute([], $companyB->id, 1);
+    $numbersB = collect($resultB['invoices'])->pluck('invoice_number');
+    expect($numbersB)->toContain('BBB-001')->not->toContain('AAA-001');
+});
+
+test('search_invoices ignores any company_id the caller tries to pass in arguments', function () {
+    $companyA = Company::first();
+    $companyB = Company::factory()->create();
+
+    $customerB = Customer::factory()->create(['company_id' => $companyB->id]);
+    Invoice::factory()->create([
+        'company_id' => $companyB->id,
+        'customer_id' => $customerB->id,
+        'invoice_number' => 'BBB-LEAK',
+    ]);
+
+    $tool = new SearchInvoicesTool;
+
+    // Simulate an LLM trying to pass company_id as an argument — even if present,
+    // the tool must ignore it because the schema doesn't include that field and
+    // the execute() method uses the injected $companyId.
+    $result = $tool->execute(
+        ['company_id' => $companyB->id, 'query' => 'BBB'],
+        $companyA->id,
+        1,
+    );
+
+    expect(collect($result['invoices'])->pluck('invoice_number'))
+        ->not->toContain('BBB-LEAK');
+});
+
+test('search_invoices respects the limit parameter with a hard cap', function () {
+    $company = Company::first();
+    $customer = Customer::factory()->create(['company_id' => $company->id]);
+
+    // Create 60 invoices — more than the max limit of 50
+    for ($i = 0; $i < 60; $i++) {
+        Invoice::factory()->create([
+            'company_id' => $company->id,
+            'customer_id' => $customer->id,
+            'invoice_number' => 'SCAN-'.str_pad((string) $i, 3, '0', STR_PAD_LEFT),
+        ]);
+    }
+
+    $tool = new SearchInvoicesTool;
+
+    // Passing limit=99 should be capped to 50
+    $result = $tool->execute(['limit' => 99], $company->id, 1);
+    expect($result['invoices'])->toHaveCount(50);
+
+    // Default limit is 10
+    $result = $tool->execute([], $company->id, 1);
+    expect($result['invoices'])->toHaveCount(10);
+});
--- a/tests/Unit/AiToolRegistryTest.php
+++ b/tests/Unit/AiToolRegistryTest.php
@@ -0,0 +1,92 @@
+<?php
+
+use App\Services\Ai\AiToolRegistry;
+use App\Services\Ai\Tools\AiTool;
+
+/**
+ * A stub tool for exercising the registry without touching any real DB tables.
+ */
+class FakeAiTool extends AiTool
+{
+    public array $lastArgs = [];
+
+    public int $lastCompanyId = 0;
+
+    public int $lastUserId = 0;
+
+    public function __construct(
+        private readonly string $toolName = 'fake_tool',
+    ) {}
+
+    public function name(): string
+    {
+        return $this->toolName;
+    }
+
+    public function description(): string
+    {
+        return 'A fake tool for tests.';
+    }
+
+    public function parameterSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'echo' => ['type' => 'string'],
+            ],
+            'required' => [],
+        ];
+    }
+
+    public function execute(array $arguments, int $companyId, int $userId): mixed
+    {
+        $this->lastArgs = $arguments;
+        $this->lastCompanyId = $companyId;
+        $this->lastUserId = $userId;
+
+        return ['echo' => $arguments['echo'] ?? null];
+    }
+}
+
+test('register stores a tool by its name', function () {
+    $registry = new AiToolRegistry;
+    $tool = new FakeAiTool;
+
+    $registry->register($tool);
+
+    expect($registry->get('fake_tool'))->toBe($tool);
+    expect($registry->all())->toHaveKey('fake_tool');
+});
+
+test('schemas returns OpenAI-format tool entries for every registered tool', function () {
+    $registry = new AiToolRegistry;
+    $registry->register(new FakeAiTool('alpha'));
+    $registry->register(new FakeAiTool('beta'));
+
+    $schemas = $registry->schemas();
+
+    expect($schemas)->toHaveCount(2);
+    expect($schemas[0]['type'])->toBe('function');
+    expect($schemas[0]['function']['name'])->toBe('alpha');
+    expect($schemas[1]['function']['name'])->toBe('beta');
+});
+
+test('execute injects companyId and userId into the tool and returns its result', function () {
+    $registry = new AiToolRegistry;
+    $tool = new FakeAiTool;
+    $registry->register($tool);
+
+    $result = $registry->execute('fake_tool', ['echo' => 'hello'], 42, 7);
+
+    expect($result)->toEqual(['echo' => 'hello']);
+    expect($tool->lastCompanyId)->toBe(42);
+    expect($tool->lastUserId)->toBe(7);
+});
+
+test('execute throws for unknown tool names', function () {
+    $registry = new AiToolRegistry;
+
+    expect(fn () => $registry->execute('nonexistent', [], 1, 1))
+        ->toThrow(InvalidArgumentException::class);
+});