Invoice Processor Agent

# Create project
mkdir invoice-processor-agent
cd invoice-processor-agent

# Initialize
npm init -y

# Install dependencies
npm install @human/sdk openai pdf-parse dotenv axios zod

# Install dev dependencies
npm install -D typescript @types/node @types/pdf-parse tsx

# Create directories
mkdir -p src/{types,utils,services} invoices/{pending,processed,failed}

HUMAN_API_KEY=your_human_api_key
OPENAI_API_KEY=your_openai_api_key
QUICKBOOKS_CLIENT_ID=your_quickbooks_client_id
QUICKBOOKS_CLIENT_SECRET=your_quickbooks_secret
AUTO_APPROVE_THRESHOLD=5000

import { z } from 'zod';

// Invoice schema with Zod for validation
export const InvoiceSchema = z.object({
  invoiceNumber: z.string().min(1),
  vendor: z.string().min(1),
  vendorAddress: z.string().optional(),
  vendorEmail: z.string().email().optional(),
  date: z.string(), // ISO 8601
  dueDate: z.string(), // ISO 8601
  subtotal: z.number().positive(),
  tax: z.number().nonnegative(),
  total: z.number().positive(),
  currency: z.string().default('USD'),
  lineItems: z
    .array(
      z.object({
        description: z.string(),
        quantity: z.number().positive(),
        unitPrice: z.number().positive(),
        amount: z.number().positive(),
      })
    )
    .min(1),
  paymentTerms: z.string().optional(),
  notes: z.string().optional(),
});

export type Invoice = z.infer<typeof InvoiceSchema>;

export interface ProcessingResult {
  invoice: Invoice;
  confidence: number;
  suggestedAction: 'auto-approve' | 'human-review' | 'reject';
  reasoning: string;
  validationErrors: string[];
}

import fs from 'fs/promises';
import pdf from 'pdf-parse';
import OpenAI from 'openai';
import { Invoice, InvoiceSchema } from '../types/invoice';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

export class InvoiceExtractor {
  /**
   * Extract text from PDF
   */
  async extractTextFromPDF(filePath: string): Promise<string> {
    const dataBuffer = await fs.readFile(filePath);
    const data = await pdf(dataBuffer);
    return data.text;
  }

  /**
   * Extract structured data using GPT-4
   */
  async extractInvoiceData(pdfPath: string): Promise<Invoice> {
    // First, extract text from PDF
    const text = await this.extractTextFromPDF(pdfPath);

    // Use GPT-4 to extract structured data
    const prompt = `Extract invoice data from this text:

${text}

Return a JSON object with this exact structure:
{
  "invoiceNumber": "string",
  "vendor": "string",
  "vendorAddress": "string (optional)",
  "vendorEmail": "string (optional)",
  "date": "YYYY-MM-DD",
  "dueDate": "YYYY-MM-DD",
  "subtotal": number,
  "tax": number,
  "total": number,
  "currency": "USD",
  "lineItems": [
    {
      "description": "string",
      "quantity": number,
      "unitPrice": number,
      "amount": number
    }
  ],
  "paymentTerms": "string (optional)",
  "notes": "string (optional)"
}

Rules:
- All monetary amounts should be numbers
- Dates must be in YYYY-MM-DD format
- Calculate totals: lineItem.amount = quantity * unitPrice
- Verify: subtotal + tax = total`;

    const response = await openai.chat.completions.create({
      model: 'gpt-4-turbo-preview',
      messages: [{ role: 'user', content: prompt }],
      response_format: { type: 'json_object' },
      temperature: 0.1, // Low temperature for accuracy
    });

    const extracted = JSON.parse(
      response.choices[0].message.content || '{}'
    );

    // Validate with Zod
    const invoice = InvoiceSchema.parse(extracted);

    return invoice;
  }

  /**
   * Calculate confidence score
   */
  calculateConfidence(invoice: Invoice): number {
    let score = 1.0;

    // Reduce confidence if missing optional fields
    if (!invoice.vendorEmail) score -= 0.1;
    if (!invoice.vendorAddress) score -= 0.05;

    // Reduce confidence if math doesn't add up
    const calculatedSubtotal = invoice.lineItems.reduce(
      (sum, item) => sum + item.amount,
      0
    );
    if (Math.abs(calculatedSubtotal - invoice.subtotal) > 0.01) {
      score -= 0.2;
    }

    return Math.max(0, Math.min(1, score));
  }
}

import { Invoice, ProcessingResult } from '../types/invoice';

export class InvoiceValidator {
  private autoApproveThreshold: number;
  private vendorWhitelist: string[];

  constructor() {
    this.autoApproveThreshold = Number(
      process.env.AUTO_APPROVE_THRESHOLD || 5000
    );
    this.vendorWhitelist = [
      'Acme Corp',
      'Widget Industries',
      'TechSupply Co',
    ];
  }

  /**
   * Validate invoice against business rules
   */
  validate(invoice: Invoice, confidence: number): ProcessingResult {
    const errors: string[] = [];
    let suggestedAction: ProcessingResult['suggestedAction'] =
      'auto-approve';
    let reasoning = '';

    // Rule 1: Check vendor whitelist
    const isWhitelistedVendor = this.vendorWhitelist.some((vendor) =>
      invoice.vendor.toLowerCase().includes(vendor.toLowerCase())
    );

    if (!isWhitelistedVendor) {
      errors.push(
        `Vendor "${invoice.vendor}" is not on the whitelist`
      );
      suggestedAction = 'human-review';
      reasoning += 'Unknown vendor. ';
    }

    // Rule 2: Check amount threshold
    if (invoice.total >= this.autoApproveThreshold) {
      errors.push(
        `Amount $${invoice.total} exceeds threshold`
      );
      suggestedAction = 'human-review';
      reasoning += 'High value invoice. ';
    }

    // Rule 3: Check confidence score
    if (confidence < 0.85) {
      errors.push(`Low confidence score: ${confidence}`);
      suggestedAction = 'human-review';
      reasoning += 'Low extraction confidence. ';
    }

    // Rule 4: Validate math
    const calculatedSubtotal = invoice.lineItems.reduce(
      (sum, item) => sum + item.amount,
      0
    );

    if (Math.abs(calculatedSubtotal - invoice.subtotal) > 0.01) {
      errors.push('Subtotal mismatch');
      suggestedAction = 'reject';
      reasoning += 'Math error. ';
    }

    // If no errors, safe to auto-approve
    if (errors.length === 0 && suggestedAction === 'auto-approve') {
      reasoning = 'All validation checks passed. Safe to auto-approve.';
    }

    return {
      invoice,
      confidence,
      suggestedAction,
      reasoning: reasoning.trim(),
      validationErrors: errors,
    };
  }
}

import { HumanClient } from '@human/sdk';
import { ProcessingResult } from '../types/invoice';

export class HumanOrchestrator {
  private client: HumanClient;
  private agentPassportId: string;
  private approverPassportId: string;

  constructor(
    agentPassportId: string,
    approverPassportId: string
  ) {
    this.client = new HumanClient({
      apiKey: process.env.HUMAN_API_KEY!,
    });
    this.agentPassportId = agentPassportId;
    this.approverPassportId = approverPassportId;
  }

  /**
   * Orchestrate invoice processing workflow
   */
  async processInvoice(processingResult: ProcessingResult) {
    console.log(`\n📄 Processing Invoice: ${processingResult.invoice.invoiceNumber}`);
    console.log(`   Vendor: ${processingResult.invoice.vendor}`);
    console.log(`   Total: $${processingResult.invoice.total}`);
    console.log(`   Confidence: ${processingResult.confidence}`);
    console.log(`   Suggested Action: ${processingResult.suggestedAction}`);

    // Create workflow
    const workflow = await this.client.humanos.orchestrate({
      task: `Process invoice ${processingResult.invoice.invoiceNumber} from ${processingResult.invoice.vendor}`,
      requiredCapabilities: [
        'invoice_processing',
        'pdf_extraction',
        'financial_validation',
      ],
      context: {
        invoice: processingResult.invoice,
        confidence: processingResult.confidence,
        validationErrors: processingResult.validationErrors,
      },
      humanInLoop:
        processingResult.suggestedAction !== 'auto-approve',
      priority:
        processingResult.invoice.total >= 10000 ? 'high' : 'normal',
    });

    console.log(`✅ Workflow created: ${workflow.workflowId}`);
    console.log(`   Status: ${workflow.status}`);

    // If auto-approve, mark as approved immediately
    if (processingResult.suggestedAction === 'auto-approve') {
      await this.approveInvoice(
        workflow.workflowId,
        'Auto-approved: All validation checks passed.'
      );
    } else {
      console.log(
        `⏸️  Waiting for human approval`
      );
    }

    return workflow;
  }

  /**
   * Approve an invoice workflow
   */
  async approveInvoice(workflowId: string, notes: string) {
    await this.client.humanos.approveWorkflow({
      workflowId,
      approvedBy: this.approverPassportId,
      notes,
    });

    console.log(`✅ Invoice approved: ${workflowId}`);
  }
}

import fs from 'fs/promises';
import path from 'path';
import dotenv from 'dotenv';
import { InvoiceExtractor } from './services/extractor';
import { InvoiceValidator } from './services/validator';
import { HumanOrchestrator } from './services/human-orchestrator';

dotenv.config();

// Replace with your actual Passport IDs
const AGENT_PASSPORT_ID = 'passport_agent_xxx';
const APPROVER_PASSPORT_ID = 'passport_approver_xxx';

const extractor = new InvoiceExtractor();
const validator = new InvoiceValidator();
const orchestrator = new HumanOrchestrator(
  AGENT_PASSPORT_ID,
  APPROVER_PASSPORT_ID
);

async function processInvoice(pdfPath: string) {
  console.log(`\n${'='.repeat(60)}`);
  console.log(`📄 Processing: ${pdfPath}`);
  console.log('='.repeat(60));

  try {
    // Step 1: Extract data from PDF
    console.log('\n1️⃣  Extracting data from PDF...');
    const invoice = await extractor.extractInvoiceData(pdfPath);
    console.log(`   Invoice #: ${invoice.invoiceNumber}`);
    console.log(`   Vendor: ${invoice.vendor}`);
    console.log(`   Total: $${invoice.total}`);

    // Step 2: Calculate confidence
    const confidence = extractor.calculateConfidence(invoice);
    console.log(`   Confidence: ${(confidence * 100).toFixed(1)}%`);

    // Step 3: Validate against business rules
    console.log('\n2️⃣  Validating against business rules...');
    const processingResult = validator.validate(invoice, confidence);

    if (processingResult.validationErrors.length > 0) {
      console.log(`   ⚠️  Validation warnings:`);
      processingResult.validationErrors.forEach((error) => {
        console.log(`      - ${error}`);
      });
    } else {
      console.log(`   ✅ All validation checks passed`);
    }

    // Step 4: Orchestrate via HumanOS
    console.log('\n3️⃣  Orchestrating workflow...');
    const workflow = await orchestrator.processInvoice(processingResult);

    // Step 5: Move to processed folder if auto-approved
    if (processingResult.suggestedAction === 'auto-approve') {
      const processedPath = path.join(
        'invoices/processed',
        path.basename(pdfPath)
      );
      await fs.rename(pdfPath, processedPath);
      console.log(`   ✅ Moved to: ${processedPath}`);
    }

    return { workflow, processingResult };
  } catch (error: any) {
    console.error(`\n❌ Error processing invoice:`, error.message);

    // Move to failed folder
    const failedPath = path.join(
      'invoices/failed',
      path.basename(pdfPath)
    );
    await fs.rename(pdfPath, failedPath);
    console.log(`   ❌ Moved to: ${failedPath}`);

    throw error;
  }
}

async function main() {
  console.log('🤖 Invoice Processor Agent Starting...\n');

  // Get all PDFs in the pending folder
  const pendingDir = 'invoices/pending';
  const files = await fs.readdir(pendingDir);
  const pdfFiles = files.filter(
    (f) => f.toLowerCase().endsWith('.pdf')
  );

  console.log(`📂 Found ${pdfFiles.length} invoices to process\n`);

  for (const file of pdfFiles) {
    const filePath = path.join(pendingDir, file);
    await processInvoice(filePath);
  }

  console.log('\n✅ All invoices processed!');
}

main().catch(console.error);

npx tsx src/setup.ts

npx tsx src/index.ts