feat(ai): job-shaped AI service with OpenAI-compatible backend, extraction-first; stop extracting every inbox document twice (#1740)

* feat(ai): job-shaped AI service with OpenAI-compatible backend, extraction-first; stop extracting every inbox document twice

Sovereign plan WS1 PR1 (#1406 Tier 2, extraction-first, aligned with the
AI surface audit).

lib/ai grows a job-shaped service (generateText / generateStructured /
extractFromDocument; no streaming members yet, see plan rule R3):
- services/anthropic-family delegates to the existing createAiClient()
  and sends the exact request literals the inbox extractor sent before
  (request-shape tests deep-equal them), so hosted Bedrock stays
  byte-identical.
- services/openai-compatible talks to any chat-completions endpoint
  (BYO Swedish provider) via Vercel AI SDK 6.x, exact-pinned and
  guarded: images as parts, PDFs rasterized with poppler (AI_PDF_MODE)
  or sent natively, AI_VISION / AI_STRICT_JSON declared, honest skips
  (ai_no_vision, pdf_rasterizer_missing) instead of fake failures.
- config.ts: AI_PROVIDER/AI_BASE_URL/AI_API_KEY/AI_MODEL and per-tier
  AI_*_MODEL with the legacy BEDROCK_* names kept as the same overrides;
  getAiStatus() is the single source of truth for "is AI wired up".
- provider.ts: openai-compatible in the auto-detect chain (after Bedrock
  and the direct API); createAiClient() refuses it loudly.

Document extraction moves onto the service and gets the audit's fixes:
- Inbox documents were extracted TWICE (pipeline A ran inside
  uploadDocument() before the inbox row existed, so its dedupe branch
  never fired; 3 707 + 1 666 calls / 30 d). The inbox now declares
  extractionOwner on the upload, the extension yields, and the inbox
  mirrors its single outcome onto document_attachments from every
  writer (sync, deferred, attach, retry, MCP).
- Every "no extraction will ever happen" outcome is stamped
  (skipped:no_ai_entitlement / ai_unconfigured / system_generated /
  ...); the status route maps the quiet ones to 'disabled' on the first
  poll instead of a 30 s client timeout. Prod showed 309 of the 327
  never-extracted uploads were the paywall working silently.
- Self-generated documents (our own invoice PDFs, payout files) are no
  longer OCR'd.
- Agent invoke answers 503 ai_unconfigured when the deployment has no
  assistant backend, distinct from the paywall.

Guard: new direct-ai-client antipattern check (shrink-only allowlist of
the pre-abstraction SDK callers) plus exact pins for @anthropic-ai/sdk,
ai and @ai-sdk/openai-compatible.

Verified: 15 958 unit tests green, guards, lint ratchet, typecheck, and a
live smoke against hosted Bedrock through the new service (ping, streamed
tool turn, thinking+cache, PDF extraction).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(ai): make AI_API_KEY optional for OpenAI-compatible endpoints (keyless local model servers)

A local model server (llama.cpp's server, Ollama /v1, LM Studio, vLLM)
usually has no auth. Before, the OpenAI-compatible backend required both
AI_BASE_URL and AI_API_KEY to count as configured, so running Accounted on a
local model meant setting a meaningless placeholder key.

- resolveAiProvider / hasAiCredentials: a base URL alone is now enough.
- services/openai-compatible: only send Authorization: Bearer when AI_API_KEY
  is set, so a keyless server is never handed an empty bearer; a hosted
  provider that needs a key still sets it.
- Docs (SELF-HOSTING Option 3: local-model example, key marked optional),
  DECISIONS.

Verified: with no AI_API_KEY, just AI_BASE_URL + AI_MODEL, getAiStatus()
reports configured=true / provider=openai-compatible (live). lib/ai suite
71 green; tsc, guards, lint clean. Bedrock/Anthropic logic unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jakob Wennberg
2026-08-20 19:39:08 +02:00
committed by GitHub
co-authored by Claude Fable 5 Jakob Wennberg
parent fbf47649f2
commit c7a75d069d
37 changed files with 2865 additions and 335 deletions
@@ -0,0 +1,158 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { createQueuedMockSupabase } from '@/tests/helpers'
const { supabase, enqueue, reset, findCalls } = createQueuedMockSupabase()
vi.mock('@/lib/supabase/server', () => ({
createServiceClient: () => supabase,
}))
const extractMock = vi.fn()
vi.mock('@/extensions/general/invoice-inbox/lib/extract-invoice-fields', () => ({
extractInvoiceFields: (...args: unknown[]) => extractMock(...args),
}))
const hasCapabilityMock = vi.fn()
vi.mock('@/lib/entitlements/has-capability', () => ({
hasCapability: (...args: unknown[]) => hasCapabilityMock(...args),
}))
const aiStatusMock = vi.fn()
vi.mock('@/lib/ai', () => ({
getAiStatus: () => aiStatusMock(),
}))
import { documentExtractionExtension } from '../index'
const handler = documentExtractionExtension.eventHandlers![0].handler
function doc(overrides: Record<string, unknown> = {}) {
return {
id: 'doc-1',
company_id: 'company-1',
file_name: 'kvitto.pdf',
mime_type: 'application/pdf',
storage_path: 'company-1/user-1/kvitto.pdf',
upload_source: 'file_upload',
...overrides,
}
}
function payload(overrides: Record<string, unknown> = {}, document = doc()) {
return { document, userId: 'user-1', companyId: 'company-1', ...overrides }
}
/** extraction_model of the LAST document_attachments update, or undefined. */
function lastStamp(): string | undefined {
const updates = findCalls('document_attachments', 'update')
const last = updates[updates.length - 1]?.[0] as { extraction_model?: string } | undefined
return last?.extraction_model
}
beforeEach(() => {
vi.clearAllMocks()
reset()
aiStatusMock.mockReturnValue({ configured: true, assistantAvailable: true })
hasCapabilityMock.mockResolvedValue(true)
extractMock.mockResolvedValue({
data: { supplier: { name: 'Elgiganten' } },
rawText: '{"supplier":{"name":"Elgiganten"}}',
model: 'eu.anthropic.claude-sonnet-5',
})
})
describe('document-extraction handler', () => {
// THE dedupe: inbox-owned documents are extracted (and mirrored) by the
// inbox itself. The handler used to race it and pay a second model call.
it('yields entirely when the inbox owns extraction', async () => {
await handler(payload({ extractionOwner: 'invoice-inbox' }))
expect(supabase.from).not.toHaveBeenCalled()
expect(extractMock).not.toHaveBeenCalled()
})
it('stamps unsupported types from the payload without reading the row', async () => {
enqueue({ data: null }) // the stamp update
await handler(payload({}, doc({ mime_type: 'application/json' })))
expect(findCalls('document_attachments', 'select')).toHaveLength(0)
expect(lastStamp()).toBe('skipped:unsupported_mime')
expect(extractMock).not.toHaveBeenCalled()
})
// Our own invoice PDFs, payout files, filings: nothing to read, paid calls
// to waste (on hosted and on a BYO-key self-host).
it('stamps system-generated documents instead of extracting them', async () => {
enqueue({ data: null })
await handler(payload({}, doc({ upload_source: 'system' })))
expect(lastStamp()).toBe('skipped:system_generated')
expect(extractMock).not.toHaveBeenCalled()
})
it('does nothing for a row that was already attempted', async () => {
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: '2026-08-20T00:00:00Z' } })
await handler(payload())
expect(findCalls('document_attachments', 'update')).toHaveLength(0)
expect(extractMock).not.toHaveBeenCalled()
})
// Self-host without an AI key: stamp so the status route answers
// 'disabled' on the first poll instead of after a 30 s timeout.
it('stamps ai_unconfigured when the deployment has no AI', async () => {
aiStatusMock.mockReturnValue({ configured: false, assistantAvailable: false })
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
await handler(payload())
expect(lastStamp()).toBe('skipped:ai_unconfigured')
expect(hasCapabilityMock).not.toHaveBeenCalled()
expect(extractMock).not.toHaveBeenCalled()
})
// The paywall, made visible: 309 of the 327 never-extracted uploads in a
// 30-day prod window belonged to companies without the ai capability.
it('stamps no_ai_entitlement for companies without the ai capability', async () => {
hasCapabilityMock.mockResolvedValue(false)
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
await handler(payload())
expect(lastStamp()).toBe('skipped:no_ai_entitlement')
expect(extractMock).not.toHaveBeenCalled()
})
it('stamps a storage download failure', async () => {
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
supabase.storage.from.mockReturnValueOnce({
download: vi.fn().mockResolvedValue({ data: null, error: { message: 'boom' } }),
})
await handler(payload())
expect(lastStamp()).toBe('failed:storage_download')
expect(extractMock).not.toHaveBeenCalled()
})
it('persists the result with the model that answered', async () => {
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
await handler(payload())
expect(extractMock).toHaveBeenCalledWith(expect.objectContaining({ mimeType: 'application/pdf', fileName: 'kvitto.pdf' }))
const updates = findCalls('document_attachments', 'update')
expect(updates[updates.length - 1][0]).toMatchObject({
extracted_data: { supplier: { name: 'Elgiganten' } },
extraction_model: 'eu.anthropic.claude-sonnet-5',
})
})
it('stamps the skip reason the extractor reports (no vision, rasterizer missing, ...)', async () => {
extractMock.mockResolvedValue({ data: {}, rawText: null, skipped: 'pdf_rasterizer_missing' })
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
await handler(payload())
expect(lastStamp()).toBe('skipped:pdf_rasterizer_missing')
})
it('stamps failed:no_raw_text when the model call produced nothing parseable', async () => {
extractMock.mockResolvedValue({ data: {}, rawText: null })
enqueue({ data: { id: 'doc-1', mime_type: 'application/pdf', storage_path: 'p', extracted_at: null } })
enqueue({ data: null })
await handler(payload())
expect(lastStamp()).toBe('failed:no_raw_text')
})
})
+109 -107
View File
@@ -1,7 +1,7 @@
import type { Extension } from '@/lib/extensions/types'
import type { SupabaseClient } from '@supabase/supabase-js'
import { extractInvoiceFields } from '@/extensions/general/invoice-inbox/lib/extract-invoice-fields'
import { toProviderModelId } from '@/lib/ai/provider'
import { getAiStatus } from '@/lib/ai'
import { hasCapability } from '@/lib/entitlements/has-capability'
import { CAPABILITY } from '@/lib/entitlements/keys'
import { createLogger } from '@/lib/logger'
@@ -10,8 +10,9 @@ import type { DocumentAttachment } from '@/types'
const log = createLogger('document-extraction')
// Mime types we know Claude can read directly via Bedrock. Anything else
// (HEIC, ZIP, TXT, …) is skipped: extracted_at still gets stamped so the
// Mime types the extraction can read (a vision model reads PDFs natively on
// Claude; OpenAI-compatible backends rasterize them). Anything else (HEIC,
// ZIP, TXT, bank JSON, …) is skipped: extracted_at still gets stamped so the
// row is marked as "attempted, not eligible".
const SUPPORTED_MIME_TYPES = new Set([
'application/pdf',
@@ -23,43 +24,65 @@ const SUPPORTED_MIME_TYPES = new Set([
// AI-extraction extension: paid AI tier only.
//
// Subscribes to the existing document.uploaded event bus topic and runs
// Sonnet 4.6 (via Bedrock, reusing invoice-inbox's extractInvoiceFields) on
// every uploaded receipt or invoice. Writes the result to
// Subscribes to the existing document.uploaded event bus topic and runs the
// configured extraction model (reusing invoice-inbox's extractInvoiceFields)
// on every uploaded receipt or invoice. Writes the result to
// document_attachments.extracted_data so the agent intent capture can use
// it without re-asking the user.
//
// Idempotency: skips when extracted_at is already set on the row. Also
// dedupes against invoice_inbox_items.extracted_data: when the inbox
// extension already extracted the same file, we copy its result instead
// of paying for a second Sonnet call.
// Idempotency: skips when extracted_at is already set on the row.
//
// Ownership: documents that enter through the invoice inbox (web upload,
// email, WhatsApp, MCP upload) are extracted by the inbox itself, which
// mirrors its result onto document_attachments when done. The inbox marks
// the upload with `extractionOwner: 'invoice-inbox'` on the event payload
// and this handler yields. It used to race instead: the inbox row did not
// exist yet when this handler ran inside uploadDocument(), so every inbox
// document was extracted twice (two paid model calls per receipt).
//
// Every outcome that means "no extraction will ever happen here" is stamped
// as `skipped:<reason>` so the polling UI stops immediately instead of
// timing out: paywall (`no_ai_entitlement`), no AI configured on this
// deployment (`ai_unconfigured`), self-generated documents (our own invoice
// PDFs, payout files: `system_generated`), unsupported types.
//
// Free tier: disable this extension in extensions.config.json. Uploads
// still work; the agent intent will see null extracted_data and either
// ask the user or call gnubok_get_document_content at chat-time.
//
// See dev_docs/specialized-agent-plan.md (§ paid/free tier note): to be
// authored.
export const documentExtractionExtension: Extension = {
id: 'document-extraction',
name: 'AI document extraction',
version: '1.0.0',
version: '1.1.0',
eventHandlers: [
{
eventType: 'document.uploaded',
handler: async (payload) => {
const { document, companyId } = payload as {
const { document, companyId, extractionOwner } = payload as {
document: DocumentAttachment
userId: string
companyId: string
extractionOwner?: 'invoice-inbox'
}
if (extractionOwner === 'invoice-inbox') return
await extractAndPersist(document, companyId)
},
},
],
}
async function stamp(
supabase: SupabaseClient,
documentId: string,
extractionModel: string
): Promise<void> {
const { error } = await supabase
.from('document_attachments')
.update({ extracted_at: new Date().toISOString(), extraction_model: extractionModel })
.eq('id', documentId)
if (error) log.warn('stamp failed', { doc: documentId, extractionModel, err: error.message })
}
async function extractAndPersist(
document: DocumentAttachment,
companyId: string,
@@ -69,9 +92,22 @@ async function extractAndPersist(
// events have no user context.
const supabase: SupabaseClient = createServiceClient()
// Cheap gates first, straight from the event payload: no DB round trip for
// the thousands of bank-statement JSON documents a sync produces.
const mimeType = (document.mime_type as string | null) ?? null
if (!mimeType || !SUPPORTED_MIME_TYPES.has(mimeType)) {
await stamp(supabase, document.id, 'skipped:unsupported_mime')
return
}
// Documents the system produced itself (our own invoice PDFs, payment
// files, filings) carry nothing to extract; reading them back with a paid
// model is waste, on hosted and doubly so on a BYO-key self-host.
if (document.upload_source === 'system') {
await stamp(supabase, document.id, 'skipped:system_generated')
return
}
// Idempotency guard: never re-extract a row that already has extracted_at.
// Note: the column may be null OR the row may not yet have the new
// schema (legacy supabase types). Fail closed on missing schema.
const { data: existing, error: existingErr } = await supabase
.from('document_attachments')
.select('id, mime_type, storage_path, extracted_at')
@@ -88,104 +124,70 @@ async function extractAndPersist(
return
}
// Dedup against inbox: if invoice-inbox already extracted this exact file
// (same document_id), copy its result to avoid a second AI call. If the
// inbox row marked the upload as skip_extraction=true, the inbox row's
// extracted_data is an empty skeleton: we must stamp the doc with a
// 'skipped:*' model so the client-side useDocumentExtraction hook reports
// 'unsupported' rather than 'succeeded' (otherwise the UI would claim AI
// finished reading a doc it never opened).
const { data: inboxRow } = await supabase
.from('invoice_inbox_items')
.select('extracted_data, extraction_skipped')
.eq('document_id', document.id)
.maybeSingle()
if (inboxRow?.extraction_skipped) {
await supabase
.from('document_attachments')
.update({
extracted_at: new Date().toISOString(),
extraction_model: 'skipped:invoice_inbox_gate',
})
.eq('id', document.id)
// No AI configured on this deployment: stamp and stop. This is the
// self-host "key not set yet" state; the status route reports it as
// disabled on the first poll instead of after a 30 s timeout.
if (!getAiStatus().configured) {
await stamp(supabase, document.id, 'skipped:ai_unconfigured')
return
}
// Paywall: the free/manual tier never triggers paid extraction. Stamp it so
// the row reads "attempted, not entitled" rather than NULL forever (which
// the polling UI could only interpret by timing out).
if (!(await hasCapability(supabase, companyId, CAPABILITY.ai))) {
log.info('extraction skipped, ai capability not entitled', { doc: document.id, companyId })
await stamp(supabase, document.id, 'skipped:no_ai_entitlement')
return
}
// Download the file from Supabase Storage. The bucket is private: the
// service-role client can read any path.
const storagePath = existing.storage_path as string | null
if (!storagePath) {
log.warn('document has no storage_path, skipping', { doc: document.id })
await stamp(supabase, document.id, 'failed:no_storage_path')
return
}
const { data: blob, error: dlErr } = await supabase.storage
.from('documents')
.download(storagePath)
if (dlErr || !blob) {
log.warn('storage download failed', { doc: document.id, err: dlErr?.message })
await stamp(supabase, document.id, 'failed:storage_download')
return
}
const buffer = Buffer.from(await blob.arrayBuffer())
let extractedData: Record<string, unknown> | null = null
let model: string = 'copied-from-invoice-inbox'
if (inboxRow?.extracted_data) {
extractedData = inboxRow.extracted_data as Record<string, unknown>
} else {
const mimeType = existing.mime_type as string | null
if (!mimeType || !SUPPORTED_MIME_TYPES.has(mimeType)) {
// Stamp the attempt so we don't keep retrying unsupported types.
await supabase
.from('document_attachments')
.update({ extracted_at: new Date().toISOString(), extraction_model: 'skipped:unsupported_mime' })
.eq('id', document.id)
let model: string
try {
const { data, rawText, model: usedModel, skipped } = await extractInvoiceFields({
buffer,
mimeType,
fileName: (document.file_name as string) || 'document',
})
// extractInvoiceFields returns an "empty" result on failure rather than
// throwing. `skipped` means no model call was made (and why); a null
// rawText with no skip means the call failed or the JSON parse did.
if (skipped) {
await stamp(supabase, document.id, `skipped:${skipped}`)
return
}
// Download the file from Supabase Storage. The bucket is private: the
// service-role client can read any path.
const storagePath = existing.storage_path as string | null
if (!storagePath) {
log.warn('document has no storage_path, skipping', { doc: document.id })
return
}
const { data: blob, error: dlErr } = await supabase.storage
.from('documents')
.download(storagePath)
if (dlErr || !blob) {
log.warn('storage download failed', { doc: document.id, err: dlErr?.message })
return
}
const buffer = Buffer.from(await blob.arrayBuffer())
if (!(await hasCapability(supabase, companyId, CAPABILITY.ai))) {
log.info('extraction skipped, ai capability not entitled', { doc: document.id, companyId })
return
}
try {
const { data, rawText } = await extractInvoiceFields({
buffer,
mimeType,
fileName: (document.file_name as string) || 'document',
})
// extractInvoiceFields returns an "empty" result on failure rather
// than throwing: distinguish by checking rawText. When rawText is
// null, the call was skipped (creds missing, unsupported type) or
// the JSON parse failed.
if (!rawText) {
await supabase
.from('document_attachments')
.update({
extracted_at: new Date().toISOString(),
extraction_model: 'failed:no_raw_text',
})
.eq('id', document.id)
return
}
extractedData = data as unknown as Record<string, unknown>
model = toProviderModelId(process.env.BEDROCK_MODEL_ID || 'claude-sonnet-5')
} catch (err) {
log.warn('extraction threw', {
doc: document.id,
err: err instanceof Error ? err.message : String(err),
})
await supabase
.from('document_attachments')
.update({
extracted_at: new Date().toISOString(),
extraction_model: 'failed:exception',
})
.eq('id', document.id)
if (!rawText) {
await stamp(supabase, document.id, 'failed:no_raw_text')
return
}
extractedData = data as unknown as Record<string, unknown>
model = usedModel ?? 'unknown'
} catch (err) {
log.warn('extraction threw', {
doc: document.id,
err: err instanceof Error ? err.message : String(err),
})
await stamp(supabase, document.id, 'failed:exception')
return
}
const { error: updateErr } = await supabase