@svgrid/enterprise 1.0.1

package/src/ai.test.ts

@@ -0,0 +1,522 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  setAIProvider, getAIProvider, hasAIProvider,
+  mockAIProvider,
+  aiFilter, aiSmartFill, aiSummarize, aiClassify,
+  type AIProvider, type AIRequest,
+} from './ai'
+import { clearLicenseKey, setLicenseKey } from './license'
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal stub of the SvGridApi surface our AI helpers depend on. We don't
+ * mock the entire grid - the AI helpers only read `getData()` and (for
+ * the `apply` branch of aiFilter) call setFilter/setSort/clearAllFilters/
+ * clearSort. Everything else stays a no-op.
+ */
+function fakeApi<T extends Record<string, unknown>>(data: T[]) {
+  const calls: Array<{ method: string; args: unknown[] }> = []
+  const log = (method: string) => (...args: unknown[]) => {
+    calls.push({ method, args })
+  }
+  const api = {
+    getData: () => data,
+    getDisplayedRows: () => data,
+    setFilter: log('setFilter'),
+    clearAllFilters: log('clearAllFilters'),
+    setSort: log('setSort'),
+    clearSort: log('clearSort'),
+    setColumnVisible: log('setColumnVisible'),
+    isColumnVisible: () => true,
+    getCellValue: () => undefined,
+    setCellValue: log('setCellValue'),
+    addRow: log('addRow'),
+    addRows: log('addRows'),
+    removeRow: log('removeRow'),
+    removeRows: log('removeRows'),
+    addColumn: log('addColumn'),
+    addColumns: log('addColumns'),
+    removeColumn: log('removeColumn'),
+    setGroupBy: log('setGroupBy'),
+    clearFilter: log('clearFilter'),
+    getFilters: () => ({}),
+    clearRowSelection: log('clearRowSelection'),
+  }
+  return { api: api as any, calls }
+}
+
+/**
+ * Build a provider that records every request it sees and replies with a
+ * caller-chosen response. Used for the deterministic-shape tests where we
+ * need to assert what the helper put into the prompt or what it does with
+ * the model's reply.
+ */
+function recordingProvider(reply: string | ((req: AIRequest) => string)) {
+  const seen: AIRequest[] = []
+  const fn: AIProvider = async (req) => {
+    seen.push(req)
+    return typeof reply === 'function' ? reply(req) : reply
+  }
+  return { provider: fn, seen }
+}
+
+// Make sure each test starts from a known state. The provider, license, and
+// any persistent flags in the AI module are global, so we reset them.
+beforeEach(() => {
+  setAIProvider(null)
+  // Default to a licensed state so the soft-gate doesn't dump noise on the
+  // console during expected-failure tests. Individual cases clear it when
+  // they want to assert soft-gate behaviour.
+  setLicenseKey('SVPRO-DEV-TEST')
+})
+afterEach(() => {
+  setAIProvider(null)
+  clearLicenseKey()
+})
+
+// ---------------------------------------------------------------------------
+// Provider plumbing
+// ---------------------------------------------------------------------------
+
+describe('AI provider registration', () => {
+  it('setAIProvider stores the function and hasAIProvider reflects it', () => {
+    expect(hasAIProvider()).toBe(false)
+    expect(getAIProvider()).toBeNull()
+
+    const fn: AIProvider = async () => '{}'
+    setAIProvider(fn)
+    expect(hasAIProvider()).toBe(true)
+    expect(getAIProvider()).toBe(fn)
+  })
+
+  it('setAIProvider(null) clears the registration', () => {
+    setAIProvider(async () => '{}')
+    setAIProvider(null)
+    expect(hasAIProvider()).toBe(false)
+  })
+
+  it('throws a typed NoProviderError when no provider is registered', async () => {
+    const { api } = fakeApi([{ id: 1, value: 10 }])
+    await expect(aiFilter(api, 'anything')).rejects.toThrow(/no AI provider registered/i)
+  })
+
+  it('throws on non-JSON when a json-format helper gets back prose', async () => {
+    const { provider } = recordingProvider('this is not JSON at all')
+    setAIProvider(provider)
+    const { api } = fakeApi([{ id: 1, value: 10 }])
+    await expect(aiFilter(api, 'find rows')).rejects.toThrow(/non-JSON/i)
+  })
+
+  it('strips a markdown ```json fence before parsing', async () => {
+    const { provider } = recordingProvider(
+      '```json\n{"filters": [], "sort": [], "rationale": "ok"}\n```',
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([{ id: 1, value: 10 }])
+    const r = await aiFilter(api, 'anything')
+    expect(r.rationale).toBe('ok')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// aiFilter
+// ---------------------------------------------------------------------------
+
+describe('aiFilter', () => {
+  it('passes the column schema to the prompt and tags the task', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({ filters: [], sort: [], rationale: 'x' }),
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([
+      { id: 'A1', amount: 100, region: 'EMEA' },
+      { id: 'A2', amount: 250, region: 'NA' },
+    ])
+    await aiFilter(api, 'show big EMEA deals')
+
+    expect(seen).toHaveLength(1)
+    const req = seen[0]!
+    expect(req.task).toBe('filter')
+    expect(req.responseFormat).toBe('json')
+    // The schema block must mention every column.
+    expect(req.prompt).toMatch(/id \(string\)/)
+    expect(req.prompt).toMatch(/amount \(number\)/)
+    expect(req.prompt).toMatch(/region \(string\)/)
+    // The user's query is forwarded verbatim.
+    expect(req.prompt).toMatch(/show big EMEA deals/)
+  })
+
+  it('drops filter / sort clauses that reference a column the grid does not have', async () => {
+    // The model hallucinates "made_up_field" - the helper must silently drop
+    // it rather than pass it through to setFilter, which would otherwise
+    // throw.
+    const reply = {
+      filters: [
+        { field: 'amount', operator: 'greaterThan', value: '100' },
+        { field: 'made_up_field', operator: 'contains', value: 'foo' },
+      ],
+      sort: [
+        { field: 'amount', desc: true },
+        { field: 'imaginary', desc: false },
+      ],
+      rationale: 'amount > 100',
+    }
+    setAIProvider(recordingProvider(JSON.stringify(reply)).provider)
+    const { api } = fakeApi([{ amount: 100, region: 'NA' }])
+    const r = await aiFilter(api, 'anything')
+
+    expect(r.filters).toHaveLength(1)
+    expect(r.filters[0]?.field).toBe('amount')
+    expect(r.sort).toHaveLength(1)
+    expect(r.sort[0]?.field).toBe('amount')
+  })
+
+  it('with apply=true applies filters and the last sort clause to the grid', async () => {
+    const reply = {
+      filters: [{ field: 'amount', operator: 'greaterThan', value: '100' }],
+      sort: [
+        { field: 'amount', desc: false },  // earlier - should be overridden
+        { field: 'amount', desc: true },   // last - this is the one applied
+      ],
+      rationale: '',
+    }
+    setAIProvider(recordingProvider(JSON.stringify(reply)).provider)
+    const { api, calls } = fakeApi([{ amount: 100, region: 'NA' }])
+    await aiFilter(api, 'q', { apply: true })
+
+    const methods = calls.map((c) => c.method)
+    expect(methods).toContain('clearAllFilters')
+    expect(methods).toContain('clearSort')
+    const setFilter = calls.find((c) => c.method === 'setFilter')!
+    expect(setFilter.args[0]).toBe('amount')
+    expect((setFilter.args[1] as any).operator).toBe('greaterThan')
+    const setSort = calls.find((c) => c.method === 'setSort')!
+    expect(setSort.args[0]).toBe('amount')
+    expect(setSort.args[1]).toBe('desc')
+  })
+
+  it('does NOT apply when apply is omitted (preview-only mode)', async () => {
+    const reply = {
+      filters: [{ field: 'amount', operator: 'greaterThan', value: '100' }],
+      sort: [{ field: 'amount', desc: true }],
+      rationale: '',
+    }
+    setAIProvider(recordingProvider(JSON.stringify(reply)).provider)
+    const { api, calls } = fakeApi([{ amount: 100, region: 'NA' }])
+    const r = await aiFilter(api, 'q')
+
+    expect(calls.find((c) => c.method === 'setFilter')).toBeUndefined()
+    expect(calls.find((c) => c.method === 'setSort')).toBeUndefined()
+    // But the result still contains the plan so the caller can render a preview.
+    expect(r.filters).toHaveLength(1)
+    expect(r.sort).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// aiSmartFill
+// ---------------------------------------------------------------------------
+
+describe('aiSmartFill', () => {
+  it('throws when no examples are provided', async () => {
+    setAIProvider(recordingProvider('{}').provider)
+    const { api } = fakeApi([{ id: 1, tier: '' }])
+    await expect(
+      aiSmartFill(api, { field: 'tier', examples: [] }),
+    ).rejects.toThrow(/requires at least one example/i)
+  })
+
+  it('auto-selects empty rows when targetRowIndices is omitted', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({
+        predictions: [{ rowIndex: 1, value: 'auto', confidence: 0.9 }],
+        rationale: '',
+      }),
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([
+      { id: 1, tier: 'enterprise' },  // already filled
+      { id: 2, tier: '' },             // empty -> picked
+      { id: 3, tier: null as unknown as string },     // null -> picked
+      { id: 4, tier: 'starter' },      // already filled
+    ])
+    await aiSmartFill(api, {
+      field: 'tier',
+      examples: [{ input: { id: 999 }, output: 'starter' }],
+    })
+
+    const prompt = seen[0]!.prompt
+    // Rows 1 and 2 (0-indexed) are the empty ones.
+    expect(prompt).toMatch(/Row 1: /)
+    expect(prompt).toMatch(/Row 2: /)
+    // Rows 0 and 3 are already filled - should NOT appear.
+    expect(prompt).not.toMatch(/Row 0: /)
+    expect(prompt).not.toMatch(/Row 3: /)
+  })
+
+  it('returns an empty prediction list when there are no empty cells', async () => {
+    setAIProvider(recordingProvider('{"predictions":[],"rationale":""}').provider)
+    const { api } = fakeApi([
+      { id: 1, tier: 'enterprise' },
+      { id: 2, tier: 'starter' },
+    ])
+    const r = await aiSmartFill(api, {
+      field: 'tier',
+      examples: [{ input: { id: 1 }, output: 'enterprise' }],
+    })
+    expect(r.predictions).toHaveLength(0)
+    expect(r.rationale).toMatch(/no empty/i)
+  })
+
+  it('respects explicit targetRowIndices', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({
+        predictions: [{ rowIndex: 0, value: 'x', confidence: 0.5 }],
+        rationale: '',
+      }),
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([
+      { id: 1, tier: 'enterprise' },
+      { id: 2, tier: 'starter' },
+    ])
+    await aiSmartFill(api, {
+      field: 'tier',
+      targetRowIndices: [0],
+      examples: [{ input: { id: 1 }, output: 'override' }],
+    })
+    expect(seen[0]!.prompt).toMatch(/Row 0: /)
+    expect(seen[0]!.prompt).not.toMatch(/Row 1: /)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// aiSummarize
+// ---------------------------------------------------------------------------
+
+describe('aiSummarize', () => {
+  it('returns a safe empty result when the slice is empty', async () => {
+    // Use a non-empty dataset but a row target that doesn't exist - the
+    // helper must short-circuit BEFORE calling the provider.
+    let calls = 0
+    setAIProvider(async () => { calls += 1; return '{}' })
+    const { api } = fakeApi([{ id: 1 }])
+    const r = await aiSummarize(api, { target: { kind: 'row', rowIndex: 99 } })
+    expect(r.text).toBe('No rows in scope.')
+    expect(r.bullets).toEqual([])
+    expect(calls).toBe(0)
+  })
+
+  it('groups by field value when target.kind = "group"', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({ text: 'ok', bullets: [], highlightedFields: [] }),
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([
+      { id: 1, region: 'NA' },
+      { id: 2, region: 'NA' },
+      { id: 3, region: 'EMEA' },
+    ])
+    const r = await aiSummarize(api, {
+      target: { kind: 'group', field: 'region', value: 'NA' },
+    })
+    expect(r.text).toBe('ok')
+    // Only the two NA rows should appear in the prompt.
+    const prompt = seen[0]!.prompt
+    expect(prompt).toMatch(/"id":1/)
+    expect(prompt).toMatch(/"id":2/)
+    expect(prompt).not.toMatch(/"id":3/)
+  })
+
+  it('samples large slices uniformly so the prompt stays under budget', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({ text: 'ok', bullets: [], highlightedFields: [] }),
+    )
+    setAIProvider(provider)
+    const rows = Array.from({ length: 200 }, (_, i) => ({ id: i }))
+    const { api } = fakeApi(rows)
+    await aiSummarize(api, { target: { kind: 'all' } })
+
+    // Default sample cap is 25. We can't easily inspect the exact sample
+    // count without parsing, but the prompt should advertise the FULL
+    // slice size while only sampling a subset (so the rendered JSON line
+    // count is ~25 rather than ~200).
+    const prompt = seen[0]!.prompt
+    expect(prompt).toMatch(/Slice size: 200 row/)
+    const jsonLines = (prompt.match(/\{"id":/g) ?? []).length
+    expect(jsonLines).toBeLessThanOrEqual(30)
+  })
+
+  it('includes the user question in the prompt when provided', async () => {
+    const { provider, seen } = recordingProvider(
+      JSON.stringify({ text: 'ok', bullets: [], highlightedFields: [] }),
+    )
+    setAIProvider(provider)
+    const { api } = fakeApi([{ id: 1 }])
+    await aiSummarize(api, {
+      target: { kind: 'all' },
+      question: 'Which accounts are at risk?',
+    })
+    expect(seen[0]!.prompt).toMatch(/Which accounts are at risk\?/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// aiClassify
+// ---------------------------------------------------------------------------
+
+describe('aiClassify', () => {
+  it('drops predictions whose value is not in the allowed class set', async () => {
+    setAIProvider(
+      recordingProvider(JSON.stringify({
+        predictions: [
+          { rowIndex: 0, value: 'at-risk',   confidence: 0.9 },
+          { rowIndex: 1, value: 'expanding', confidence: 0.8 },
+          // Hallucinated label - must be dropped.
+          { rowIndex: 2, value: 'something-else', confidence: 0.95 },
+        ],
+      })).provider,
+    )
+    const { api } = fakeApi([
+      { notes: 'losing momentum' },
+      { notes: 'expanding fast' },
+      { notes: 'unclear' },
+    ])
+    const r = await aiClassify(api, {
+      inputField: 'notes',
+      outputField: 'sentiment',
+      classes: ['at-risk', 'expanding', 'steady'],
+    })
+    expect(r.predictions).toHaveLength(2)
+    expect(r.predictions.find((p) => p.value === 'something-else')).toBeUndefined()
+  })
+
+  it('includes the rubric in the prompt when classDescriptions is provided', async () => {
+    const { provider, seen } = recordingProvider('{"predictions":[]}')
+    setAIProvider(provider)
+    const { api } = fakeApi([{ notes: 'x' }])
+    await aiClassify(api, {
+      inputField: 'notes',
+      outputField: 'sentiment',
+      classes: ['at-risk', 'steady'],
+      classDescriptions: {
+        'at-risk': 'churn signals',
+        steady:   'no signals',
+      },
+    })
+    expect(seen[0]!.prompt).toMatch(/- at-risk: churn signals/)
+    expect(seen[0]!.prompt).toMatch(/- steady: no signals/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// mockAIProvider end-to-end
+// ---------------------------------------------------------------------------
+
+describe('mockAIProvider', () => {
+  it('round-trips through aiFilter with at least one sensible clause', async () => {
+    setAIProvider(mockAIProvider)
+    const { api } = fakeApi([
+      { id: 'A1', arr: 100_000, region: 'EMEA',  owner: 'Sasha' },
+      { id: 'A2', arr: 250_000, region: 'NA',    owner: 'Jamie' },
+      { id: 'A3', arr:  50_000, region: 'APAC',  owner: 'Casey' },
+    ])
+    const r = await aiFilter(api, 'show accounts over $80k in EMEA, highest first')
+    // Should have inferred something about "over $80k", "EMEA", and a sort.
+    const fields = r.filters.map((f) => f.field)
+    expect(fields).toContain('arr')
+    expect(fields).toContain('region')
+    expect(r.sort.length).toBeGreaterThan(0)
+    expect(r.rationale).toMatch(/Interpreted/i)
+  })
+
+  it('round-trips through aiClassify and returns labels from the allowed set', async () => {
+    setAIProvider(mockAIProvider)
+    const { api } = fakeApi([
+      { id: 1, notes: 'champion left, ARR at risk' },
+      { id: 2, notes: 'expanding into two new regions' },
+      { id: 3, notes: 'steady usage no surprises' },
+    ])
+    const r = await aiClassify(api, {
+      inputField: 'notes',
+      outputField: 'sentiment',
+      classes: ['at-risk', 'expanding', 'steady'],
+    })
+    expect(r.predictions.length).toBeGreaterThan(0)
+    for (const p of r.predictions) {
+      expect(['at-risk', 'expanding', 'steady']).toContain(p.value)
+      expect(p.confidence).toBeGreaterThan(0)
+      expect(p.confidence).toBeLessThanOrEqual(1)
+    }
+  })
+
+  it('summarises the whole view via the mock', async () => {
+    setAIProvider(mockAIProvider)
+    const { api } = fakeApi(Array.from({ length: 12 }, (_, i) => ({ id: i, value: i * 100 })))
+    const r = await aiSummarize(api, { target: { kind: 'all' } })
+    expect(r.text).toMatch(/12 rows in scope/i)
+    expect(r.bullets.length).toBeGreaterThan(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// License soft-gate
+// ---------------------------------------------------------------------------
+
+describe('license interaction', () => {
+  it('AI calls still succeed without a license key (soft-gate)', async () => {
+    clearLicenseKey()
+    setAIProvider(mockAIProvider)
+    const { api } = fakeApi([{ id: 1 }])
+    // Should NOT throw - the soft-gate emits a console nudge then proceeds.
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      const r = await aiFilter(api, 'anything')
+      expect(r).toBeDefined()
+    } finally {
+      consoleSpy.mockRestore()
+    }
+  })
+
+  it('AI calls throw on a malformed license prefix', async () => {
+    setLicenseKey('NOT-A-VALID-PREFIX-AT-ALL')
+    setAIProvider(mockAIProvider)
+    const { api } = fakeApi([{ id: 1 }])
+    await expect(aiFilter(api, 'q')).rejects.toThrow(/invalid license/i)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Abort + cancellation
+// ---------------------------------------------------------------------------
+
+describe('cancellation', () => {
+  it('forwards the AbortSignal to the provider for aiFilter', async () => {
+    let receivedSignal: AbortSignal | undefined
+    const provider: AIProvider = async (req) => {
+      receivedSignal = req.signal
+      return JSON.stringify({ filters: [], sort: [], rationale: '' })
+    }
+    setAIProvider(provider)
+    const controller = new AbortController()
+    const { api } = fakeApi([{ id: 1 }])
+    await aiFilter(api, 'q', { signal: controller.signal })
+    expect(receivedSignal).toBe(controller.signal)
+  })
+
+  it('forwards the AbortSignal for aiSummarize', async () => {
+    let receivedSignal: AbortSignal | undefined
+    const provider: AIProvider = async (req) => {
+      receivedSignal = req.signal
+      return JSON.stringify({ text: '', bullets: [], highlightedFields: [] })
+    }
+    setAIProvider(provider)
+    const controller = new AbortController()
+    const { api } = fakeApi([{ id: 1 }])
+    await aiSummarize(api, { target: { kind: 'all' }, signal: controller.signal })
+    expect(receivedSignal).toBe(controller.signal)
+  })
+})