QT/InvoiceShelf
1
0
Fork 0
mirror of https://github.com/InvoiceShelf/InvoiceShelf.git synced 2026-07-17 06:15:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Darko Gjorgjijoski
2026-04-12 08:00:00 +02:00
parent c7fab5d52f
commit e861fc1fc1
39 changed files with 2776 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
tests/Unit/AiToolRegistryTest.php Normal file
View File

@@ -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);
});