feat(tests): integrate SmartAi/DualAgentOrchestrator into extraction tests and add JSON self-validation

This commit is contained in:
2026-01-20 01:17:41 +00:00
parent b202e024a4
commit 77d57e80bd
7 changed files with 562 additions and 575 deletions

View File

@@ -1,9 +1,10 @@
/**
* Bank statement extraction using MiniCPM-V (visual extraction)
* Bank statement extraction using MiniCPM-V via smartagent DualAgentOrchestrator
*
* JSON per-page approach with streaming output:
* 1. Ask for structured JSON of all transactions per page
* 2. Single pass extraction (no consensus)
* Uses vision-capable orchestrator with JsonValidatorTool for self-validation:
* 1. Process each page with the orchestrator
* 2. Driver extracts transactions and validates JSON before completing
* 3. Streaming output during extraction
*/
import { tap, expect } from '@git.zone/tstest/tapbundle';
import * as fs from 'fs';
@@ -11,6 +12,8 @@ import * as path from 'path';
import { execSync } from 'child_process';
import * as os from 'os';
import { ensureMiniCpm } from './helpers/docker.js';
import { SmartAi } from '@push.rocks/smartai';
import { DualAgentOrchestrator, JsonValidatorTool } from '@push.rocks/smartagent';
const OLLAMA_URL = 'http://localhost:11434';
const MODEL = 'openbmb/minicpm-v4.5:q8_0';
@@ -21,21 +24,9 @@ interface ITransaction {
amount: number;
}
const JSON_PROMPT = `Extract ALL transactions from this bank statement page as a JSON array.
IMPORTANT RULES:
1. Each transaction has: date, description/counterparty, and an amount
2. Amount is NEGATIVE for money going OUT (debits, payments, withdrawals)
3. Amount is POSITIVE for money coming IN (credits, deposits, refunds)
4. Date format: YYYY-MM-DD
5. Do NOT include: opening balance, closing balance, subtotals, headers, or summary rows
6. Only include actual transactions with a specific date and amount
Return ONLY this JSON format, no explanation:
[
{"date": "2021-06-01", "counterparty": "COMPANY NAME", "amount": -25.99},
{"date": "2021-06-02", "counterparty": "DEPOSIT FROM", "amount": 100.00}
]`;
// SmartAi instance and orchestrator (initialized in setup)
let smartAi: SmartAi;
let orchestrator: DualAgentOrchestrator;
/**
* Convert PDF to PNG images using ImageMagick
@@ -65,231 +56,31 @@ function convertPdfToImages(pdfPath: string): string[] {
}
}
/**
* Query for JSON extraction with streaming output
*/
async function queryJson(image: string, queryId: string): Promise<string> {
const startTime = Date.now();
process.stdout.write(` [${queryId}] `);
const EXTRACTION_PROMPT = `Extract ALL transactions from this bank statement page as a JSON array.
const response = await fetch(`${OLLAMA_URL}/api/chat`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
model: MODEL,
messages: [{
role: 'user',
content: JSON_PROMPT,
images: [image],
}],
stream: true,
options: {
num_ctx: 32768,
num_predict: 4000,
temperature: 0.1,
},
}),
});
IMPORTANT RULES:
1. Each transaction has: date, counterparty (description), and an amount
2. Amount is NEGATIVE for money going OUT (debits, payments, withdrawals)
3. Amount is POSITIVE for money coming IN (credits, deposits, refunds)
4. Date format: YYYY-MM-DD
5. Do NOT include: opening balance, closing balance, subtotals, headers, or summary rows
6. Only include actual transactions with a specific date and amount
if (!response.ok) {
const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
process.stdout.write(`ERROR: ${response.status} (${elapsed}s)\n`);
throw new Error(`Ollama API error: ${response.status}`);
}
Before completing, validate your JSON output:
let content = '';
const reader = response.body!.getReader();
const decoder = new TextDecoder();
<tool_call>
<tool>json</tool>
<action>validate</action>
<params>{"jsonString": "YOUR_JSON_ARRAY_HERE"}</params>
</tool_call>
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
Output format (must be a valid JSON array):
[
{"date": "2021-06-01", "counterparty": "COMPANY NAME", "amount": -25.99},
{"date": "2021-06-02", "counterparty": "DEPOSIT FROM", "amount": 100.00}
]
const chunk = decoder.decode(value, { stream: true });
for (const line of chunk.split('\n').filter(l => l.trim())) {
try {
const json = JSON.parse(line);
const token = json.message?.content || '';
if (token) {
process.stdout.write(token);
content += token;
}
} catch {
// Ignore parse errors for partial chunks
}
}
}
} finally {
const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
process.stdout.write(` (${elapsed}s)\n`);
}
return content.trim();
}
/**
* Sanitize JSON string - fix common issues from vision model output
*/
function sanitizeJson(jsonStr: string): string {
let s = jsonStr;
// Fix +number (e.g., +93.80 -> 93.80) - JSON doesn't allow + prefix
// Handle various whitespace patterns
s = s.replace(/"amount"\s*:\s*\+/g, '"amount": ');
s = s.replace(/:\s*\+(\d)/g, ': $1');
// Fix European number format with thousands separator (e.g., 1.000.00 -> 1000.00)
// Pattern: "amount": X.XXX.XX where X.XXX is thousands and .XX is decimal
s = s.replace(/"amount"\s*:\s*(-?)(\d{1,3})\.(\d{3})\.(\d{2})\b/g, '"amount": $1$2$3.$4');
// Also handle larger numbers like 10.000.00
s = s.replace(/"amount"\s*:\s*(-?)(\d{1,3})\.(\d{3})\.(\d{3})\.(\d{2})\b/g, '"amount": $1$2$3$4.$5');
// Fix trailing commas before ] or }
s = s.replace(/,\s*([}\]])/g, '$1');
// Fix unescaped newlines inside strings (replace with space)
s = s.replace(/"([^"\\]*)\n([^"]*)"/g, '"$1 $2"');
// Fix unescaped tabs inside strings
s = s.replace(/"([^"\\]*)\t([^"]*)"/g, '"$1 $2"');
// Fix unescaped backslashes (but not already escaped ones)
s = s.replace(/\\(?!["\\/bfnrtu])/g, '\\\\');
// Fix common issues with counterparty names containing special chars
s = s.replace(/"counterparty":\s*"([^"]*)'([^"]*)"/g, '"counterparty": "$1$2"');
// Remove control characters except newlines (which we handle above)
s = s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, ' ');
return s;
}
/**
* Parse JSON response into transactions
*/
function parseJsonResponse(response: string, queryId: string): ITransaction[] {
console.log(` [${queryId}] Parsing response...`);
// Try to find JSON in markdown code block
const codeBlockMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
let jsonStr = codeBlockMatch ? codeBlockMatch[1].trim() : response.trim();
if (codeBlockMatch) {
console.log(` [${queryId}] Found JSON in code block`);
}
// Sanitize JSON (fix +number issue)
jsonStr = sanitizeJson(jsonStr);
try {
const parsed = JSON.parse(jsonStr);
if (Array.isArray(parsed)) {
const txs = parsed.map(tx => ({
date: String(tx.date || ''),
counterparty: String(tx.counterparty || tx.description || ''),
amount: parseAmount(tx.amount),
}));
console.log(` [${queryId}] Parsed ${txs.length} transactions (direct)`);
return txs;
}
console.log(` [${queryId}] Parsed JSON is not an array`);
} catch (e) {
const errMsg = (e as Error).message;
console.log(` [${queryId}] Direct parse failed: ${errMsg}`);
// Log problematic section with context
const posMatch = errMsg.match(/position (\d+)/);
if (posMatch) {
const pos = parseInt(posMatch[1]);
const start = Math.max(0, pos - 40);
const end = Math.min(jsonStr.length, pos + 40);
const context = jsonStr.substring(start, end);
const marker = ' '.repeat(pos - start) + '^';
console.log(` [${queryId}] Context around error position ${pos}:`);
console.log(` [${queryId}] ...${context}...`);
console.log(` [${queryId}] ${marker}`);
}
// Try to find JSON array pattern
const arrayMatch = jsonStr.match(/\[[\s\S]*\]/);
if (arrayMatch) {
console.log(` [${queryId}] Found array pattern, trying to parse...`);
const sanitizedArray = sanitizeJson(arrayMatch[0]);
try {
const parsed = JSON.parse(sanitizedArray);
if (Array.isArray(parsed)) {
const txs = parsed.map(tx => ({
date: String(tx.date || ''),
counterparty: String(tx.counterparty || tx.description || ''),
amount: parseAmount(tx.amount),
}));
console.log(` [${queryId}] Parsed ${txs.length} transactions (array match)`);
return txs;
}
} catch (e2) {
const errMsg2 = (e2 as Error).message;
console.log(` [${queryId}] Array parse failed: ${errMsg2}`);
const posMatch2 = errMsg2.match(/position (\d+)/);
if (posMatch2) {
const pos2 = parseInt(posMatch2[1]);
console.log(` [${queryId}] Context around error: ...${sanitizedArray.substring(Math.max(0, pos2 - 30), pos2 + 30)}...`);
}
// Try to extract individual objects from the malformed array
console.log(` [${queryId}] Attempting object-by-object extraction...`);
const extracted = extractTransactionsFromMalformedJson(sanitizedArray, queryId);
if (extracted.length > 0) {
console.log(` [${queryId}] Recovered ${extracted.length} transactions via object extraction`);
return extracted;
}
}
} else {
console.log(` [${queryId}] No array pattern found in response`);
console.log(` [${queryId}] Raw response preview: ${response.substring(0, 200)}...`);
}
}
console.log(` [${queryId}] PARSE FAILED - returning empty array`);
return [];
}
/**
* Extract transactions from malformed JSON by parsing objects individually
*/
function extractTransactionsFromMalformedJson(jsonStr: string, queryId: string): ITransaction[] {
const transactions: ITransaction[] = [];
// Match individual transaction objects
const objectPattern = /\{\s*"date"\s*:\s*"([^"]+)"\s*,\s*"counterparty"\s*:\s*"([^"]+)"\s*,\s*"amount"\s*:\s*([+-]?\d+\.?\d*)\s*\}/g;
let match;
while ((match = objectPattern.exec(jsonStr)) !== null) {
transactions.push({
date: match[1],
counterparty: match[2],
amount: parseFloat(match[3]),
});
}
// Also try with different field orders (amount before counterparty, etc.)
if (transactions.length === 0) {
const altPattern = /\{\s*"date"\s*:\s*"([^"]+)"[^}]*"amount"\s*:\s*([+-]?\d+\.?\d*)[^}]*\}/g;
while ((match = altPattern.exec(jsonStr)) !== null) {
// Try to extract counterparty from the match
const counterpartyMatch = match[0].match(/"counterparty"\s*:\s*"([^"]+)"/);
const descMatch = match[0].match(/"description"\s*:\s*"([^"]+)"/);
transactions.push({
date: match[1],
counterparty: counterpartyMatch?.[1] || descMatch?.[1] || 'UNKNOWN',
amount: parseFloat(match[2]),
});
}
}
return transactions;
}
Only complete after validation passes. Output the final JSON array in <task_complete> tags.`;
/**
* Parse amount from various formats
@@ -309,20 +100,92 @@ function parseAmount(value: unknown): number {
}
/**
* Extract transactions from a single page (single pass)
* Extract JSON from response (handles markdown code blocks and task_complete tags)
*/
function extractJsonFromResponse(response: string): unknown[] | null {
// Try to find JSON in task_complete tags
const completeMatch = response.match(/<task_complete>([\s\S]*?)<\/task_complete>/);
if (completeMatch) {
const content = completeMatch[1].trim();
// Try to find JSON in the content
const codeBlockMatch = content.match(/```(?:json)?\s*([\s\S]*?)```/);
const jsonStr = codeBlockMatch ? codeBlockMatch[1].trim() : content;
try {
const parsed = JSON.parse(jsonStr);
if (Array.isArray(parsed)) return parsed;
} catch {
// Try to find JSON array pattern
const jsonMatch = jsonStr.match(/\[[\s\S]*\]/);
if (jsonMatch) {
try {
const parsed = JSON.parse(jsonMatch[0]);
if (Array.isArray(parsed)) return parsed;
} catch {
return null;
}
}
}
}
// Try to find JSON in markdown code block
const codeBlockMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
const jsonStr = codeBlockMatch ? codeBlockMatch[1].trim() : response.trim();
try {
const parsed = JSON.parse(jsonStr);
if (Array.isArray(parsed)) return parsed;
} catch {
// Try to find JSON array pattern
const jsonMatch = jsonStr.match(/\[[\s\S]*\]/);
if (jsonMatch) {
try {
const parsed = JSON.parse(jsonMatch[0]);
if (Array.isArray(parsed)) return parsed;
} catch {
return null;
}
}
}
return null;
}
/**
* Parse JSON response into transactions
*/
function parseJsonToTransactions(response: string): ITransaction[] {
const parsed = extractJsonFromResponse(response);
if (!parsed || !Array.isArray(parsed)) return [];
return parsed.map((tx: any) => ({
date: String(tx.date || ''),
counterparty: String(tx.counterparty || tx.description || ''),
amount: parseAmount(tx.amount),
}));
}
/**
* Extract transactions from a single page using smartagent orchestrator
*/
async function extractTransactionsFromPage(image: string, pageNum: number): Promise<ITransaction[]> {
console.log(`\n ======== Page ${pageNum} ========`);
const queryId = `P${pageNum}`;
const response = await queryJson(image, queryId);
const transactions = parseJsonResponse(response, queryId);
const startTime = Date.now();
const result = await orchestrator.run(EXTRACTION_PROMPT, { images: [image] });
const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
console.log(`\n [Page ${pageNum}] Completed in ${elapsed}s (${result.iterations} iterations, status: ${result.status})`);
const transactions = parseJsonToTransactions(result.result);
console.log(` [Page ${pageNum}] Extracted ${transactions.length} transactions:`);
for (let i = 0; i < transactions.length; i++) {
for (let i = 0; i < Math.min(transactions.length, 10); i++) {
const tx = transactions[i];
console.log(` ${(i + 1).toString().padStart(2)}. ${tx.date} | ${tx.counterparty.substring(0, 30).padEnd(30)} | ${tx.amount >= 0 ? '+' : ''}${tx.amount.toFixed(2)}`);
}
if (transactions.length > 10) {
console.log(` ... and ${transactions.length - 10} more transactions`);
}
return transactions;
}
@@ -331,7 +194,7 @@ async function extractTransactionsFromPage(image: string, pageNum: number): Prom
* Extract all transactions from bank statement
*/
async function extractTransactions(images: string[]): Promise<ITransaction[]> {
console.log(` [Vision] Processing ${images.length} page(s) with ${MODEL} (single pass)`);
console.log(` [Vision] Processing ${images.length} page(s) with smartagent DualAgentOrchestrator`);
const allTransactions: ITransaction[] = [];
@@ -426,6 +289,80 @@ tap.test('setup: ensure Docker containers are running', async () => {
console.log('\n[Setup] All containers ready!\n');
});
tap.test('setup: initialize smartagent orchestrator', async () => {
console.log('[Setup] Initializing SmartAi and DualAgentOrchestrator...');
smartAi = new SmartAi({
ollama: {
baseUrl: OLLAMA_URL,
model: MODEL,
defaultOptions: {
num_ctx: 32768,
num_predict: 4000,
temperature: 0.1,
},
defaultTimeout: 300000, // 5 minutes for vision tasks
},
});
await smartAi.start();
orchestrator = new DualAgentOrchestrator({
smartAiInstance: smartAi,
defaultProvider: 'ollama',
guardianPolicyPrompt: `You are a Guardian agent overseeing bank statement extraction tasks.
APPROVE all tool calls that:
- Use the json.validate action to verify JSON output
- Are reasonable attempts to complete the extraction task
REJECT tool calls that:
- Attempt to access external resources
- Try to execute arbitrary code
- Are clearly unrelated to bank statement extraction`,
driverSystemMessage: `You are an AI assistant that extracts bank transactions from statement images.
Your task is to analyze bank statement images and extract transaction data.
You have access to a json.validate tool to verify your JSON output.
IMPORTANT: Always validate your JSON before completing the task.
## Tool Usage Format
When you need to validate JSON, output:
<tool_call>
<tool>json</tool>
<action>validate</action>
<params>{"jsonString": "YOUR_JSON_ARRAY"}</params>
</tool_call>
## Completion Format
After validation passes, complete the task:
<task_complete>
[{"date": "YYYY-MM-DD", "counterparty": "...", "amount": -123.45}, ...]
</task_complete>`,
maxIterations: 5,
maxConsecutiveRejections: 3,
onToken: (token, source) => {
if (source === 'driver') {
process.stdout.write(token);
}
},
onProgress: (event) => {
if (event.logLevel === 'error') {
console.error(event.logMessage);
}
},
});
// Register the JsonValidatorTool
orchestrator.registerTool(new JsonValidatorTool());
await orchestrator.start();
console.log('[Setup] Orchestrator initialized!\n');
});
tap.test('should have MiniCPM-V model loaded', async () => {
const response = await fetch(`${OLLAMA_URL}/api/tags`);
const data = await response.json();
@@ -434,7 +371,7 @@ tap.test('should have MiniCPM-V model loaded', async () => {
});
const testCases = findTestCases();
console.log(`\nFound ${testCases.length} bank statement test cases (MiniCPM-V)\n`);
console.log(`\nFound ${testCases.length} bank statement test cases (smartagent + MiniCPM-V)\n`);
let passedCount = 0;
let failedCount = 0;
@@ -466,7 +403,10 @@ for (const testCase of testCases) {
// Log counterparty variations (names that differ but date/amount matched)
if (result.variations.length > 0) {
console.log(` Counterparty variations (${result.variations.length}):`);
result.variations.forEach((v) => console.log(` ${v}`));
result.variations.slice(0, 5).forEach((v) => console.log(` ${v}`));
if (result.variations.length > 5) {
console.log(` ... and ${result.variations.length - 5} more variations`);
}
}
expect(result.matches).toEqual(result.total);
@@ -474,12 +414,20 @@ for (const testCase of testCases) {
});
}
tap.test('cleanup: stop orchestrator', async () => {
if (orchestrator) {
await orchestrator.stop();
}
console.log('[Cleanup] Orchestrator stopped');
});
tap.test('summary', async () => {
const total = testCases.length;
console.log(`\n======================================================`);
console.log(` Bank Statement Summary (${MODEL})`);
console.log(` Bank Statement Summary`);
console.log(` (smartagent + ${MODEL})`);
console.log(`======================================================`);
console.log(` Method: JSON per-page (single pass)`);
console.log(` Method: DualAgentOrchestrator with vision`);
console.log(` Passed: ${passedCount}/${total}`);
console.log(` Failed: ${failedCount}/${total}`);
console.log(`======================================================\n`);