mirror of
https://github.com/InvoiceShelf/InvoiceShelf.git
synced 2026-07-18 06:45:20 +00:00
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.
This commit is contained in:
Darko Gjorgjijoski
108
app/Services/Ai/Tools/SearchInvoicesTool.php
Normal file
108
app/Services/Ai/Tools/SearchInvoicesTool.php
Normal file
@@ -0,0 +1,108 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Ai\Tools;
|
||||
|
||||
use App\Models\Invoice;
|
||||
|
||||
/**
|
||||
* Search invoices by free text, status, and/or customer, scoped to the current company.
|
||||
*
|
||||
* Returns a compact list — no line items, no taxes. For full details the LLM
|
||||
* should follow up with GetInvoiceTool using the returned invoice_number.
|
||||
*/
|
||||
class SearchInvoicesTool extends AiTool
|
||||
{
|
||||
private const DEFAULT_LIMIT = 10;
|
||||
|
||||
private const MAX_LIMIT = 50;
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'search_invoices';
|
||||
}
|
||||
|
||||
public function description(): string
|
||||
{
|
||||
return 'Search invoices for the current company. Filter by free-text query (matches invoice number and reference), status, or customer_id. Returns a compact list with invoice numbers, customers, dates, totals, and statuses.';
|
||||
}
|
||||
|
||||
public function parameterSchema(): array
|
||||
{
|
||||
return [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'query' => [
|
||||
'type' => 'string',
|
||||
'description' => 'Optional free-text search against invoice_number and reference_number.',
|
||||
],
|
||||
'status' => [
|
||||
'type' => 'string',
|
||||
'enum' => ['DRAFT', 'SENT', 'VIEWED', 'COMPLETED', 'UNPAID', 'PARTIALLY_PAID', 'PAID', 'OVERDUE'],
|
||||
'description' => 'Optional status filter.',
|
||||
],
|
||||
'customer_id' => [
|
||||
'type' => 'integer',
|
||||
'description' => 'Optional customer ID to restrict to a specific customer.',
|
||||
],
|
||||
'limit' => [
|
||||
'type' => 'integer',
|
||||
'minimum' => 1,
|
||||
'maximum' => self::MAX_LIMIT,
|
||||
'description' => 'Max rows to return (default 10, max 50).',
|
||||
],
|
||||
],
|
||||
'required' => [],
|
||||
];
|
||||
}
|
||||
|
||||
public function execute(array $arguments, int $companyId, int $userId): mixed
|
||||
{
|
||||
$limit = min((int) ($arguments['limit'] ?? self::DEFAULT_LIMIT), self::MAX_LIMIT);
|
||||
|
||||
$query = Invoice::query()
|
||||
->where('company_id', $companyId)
|
||||
->with('customer:id,name')
|
||||
->latest('invoice_date')
|
||||
->limit($limit);
|
||||
|
||||
if (! empty($arguments['query'])) {
|
||||
$q = $arguments['query'];
|
||||
$query->where(function ($qb) use ($q) {
|
||||
$qb->where('invoice_number', 'like', "%{$q}%")
|
||||
->orWhere('reference_number', 'like', "%{$q}%");
|
||||
});
|
||||
}
|
||||
|
||||
if (! empty($arguments['status'])) {
|
||||
$status = strtoupper((string) $arguments['status']);
|
||||
// 'PAID' / 'UNPAID' / 'PARTIALLY_PAID' live on paid_status; the rest on status.
|
||||
if (in_array($status, ['PAID', 'UNPAID', 'PARTIALLY_PAID'], true)) {
|
||||
$query->where('paid_status', $status);
|
||||
} elseif ($status === 'OVERDUE') {
|
||||
$query->where('overdue', true);
|
||||
} else {
|
||||
$query->where('status', $status);
|
||||
}
|
||||
}
|
||||
|
||||
if (! empty($arguments['customer_id'])) {
|
||||
$query->where('customer_id', (int) $arguments['customer_id']);
|
||||
}
|
||||
|
||||
return [
|
||||
'invoices' => $query->get()->map(fn (Invoice $inv): array => [
|
||||
'id' => $inv->id,
|
||||
'invoice_number' => $inv->invoice_number,
|
||||
'customer_id' => $inv->customer_id,
|
||||
'customer_name' => $inv->customer?->name,
|
||||
'invoice_date' => $this->asDate($inv->invoice_date),
|
||||
'due_date' => $this->asDate($inv->due_date),
|
||||
'status' => $inv->status,
|
||||
'paid_status' => $inv->paid_status,
|
||||
'total' => $inv->total,
|
||||
'due_amount' => $inv->due_amount,
|
||||
'overdue' => (bool) $inv->overdue,
|
||||
])->all(),
|
||||
];
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user