Invoicify JSON Craft

AI-powered invoice to JSON converter using Mistral AI with dynamic field detection and master schema management.

Features

• 🤖 AI-Powered Extraction: Uses Mistral AI for accurate invoice data extraction
• 📋 Master Schema Management: Maintains a dynamic schema that grows with your data
• 🔍 Auto Field Detection: Automatically detects and adds new fields to the master schema
• 🎯 High Accuracy: Built-in confidence scoring for extraction quality
• 📁 Multiple Input Formats: Supports file paths and base64 images
• 🛠️ TypeScript Support: Full TypeScript definitions included

Installation

npm install invoicify-json-craft

or

yarn add invoicify-json-craft

Quick Start

JavaScript

const { InvoiceProcessor } = require('invoicify-json-craft');

// Initialize the processor with your Mistral API key
const processor = new InvoiceProcessor({
  apiKey: 'your-mistral-api-key-here'
});

// Process an invoice from image path
async function processInvoice() {
  try {
    const result = await processor.processInvoice({
      imagePath: './path/to/invoice.jpg'
    });
    
    console.log('Extracted Data:', result.extractedData);
    console.log('New Fields Detected:', result.newFieldsDetected);
    console.log('Confidence:', result.confidence);
  } catch (error) {
    console.error('Processing failed:', error.message);
  }
}

processInvoice();

TypeScript

import { InvoiceProcessor, ProcessedInvoice } from 'invoicify-json-craft';

const processor = new InvoiceProcessor({
  apiKey: process.env.MISTRAL_API_KEY!,
  model: 'mistral-large-latest', // optional
  temperature: 0.1 // optional
});

async function processInvoice(): Promise<void> {
  try {
    const result: ProcessedInvoice = await processor.processInvoice({
      imagePath: './invoice.png'
    });
    
    console.log('Invoice Data:', result.extractedData);
    console.log('Processing Time:', result.processingTime, 'ms');
  } catch (error) {
    console.error('Error:', error);
  }
}

Python Equivalent

# Note: This is a JavaScript/Node.js package
# For Python, you would need to implement similar logic using requests
import requests
import base64
import json

class InvoiceProcessor:
    def __init__(self, api_key, model="mistral-large-latest"):
        self.api_key = api_key
        self.model = model
    
    def process_invoice(self, image_path):
        with open(image_path, "rb") as image_file:
            base64_image = base64.b64encode(image_file.read()).decode('utf-8')
            
        # Implementation similar to the Node.js version
        # Full Python package coming soon!

Configuration Options

const processor = new InvoiceProcessor({
  apiKey: 'your-api-key',           // Required: Your Mistral AI API key
  model: 'mistral-large-latest',    // Optional: AI model to use
  temperature: 0.1,                 // Optional: Response creativity (0-1)
  maxTokens: 2000,                  // Optional: Maximum response length
  customMasterSchema: []            // Optional: Custom field definitions
});

Master Schema Management

The package automatically maintains a master schema of invoice fields. When new fields are detected in processed invoices, they're automatically added to the schema.

// Get current master schema
const schema = processor.getMasterSchema();
console.log('Current fields:', schema);

// Add custom field
processor.addCustomField({
  name: 'departmentCode',
  type: 'string',
  required: false,
  description: 'Department identifier'
});

// Remove field
processor.removeCustomField('oldFieldName');

Default Master Schema Fields

The package comes with a comprehensive set of standard invoice fields:

• invoiceNumber (string, required)
• invoiceDate (date, required)
• totalAmount (number, required)
• vendorName (string, required)
• dueDate (date)
• subtotal (number)
• taxAmount (number)
• currency (string)
• customerName (string)
• items (array)
• And many more...

API Reference

InvoiceProcessor

Constructor

• new InvoiceProcessor(config: InvoiceProcessorConfig)

Methods

• processInvoice(options): Process an invoice image
• getMasterSchema(): Get current field schema
• addCustomField(field): Add custom field definition
• removeCustomField(fieldName): Remove field from schema

Types

interface ProcessedInvoice {
  extractedData: Record<string, any>;
  newFieldsDetected: string[];
  confidence: number;
  processingTime: number;
}

interface InvoiceField {
  name: string;
  type: 'string' | 'number' | 'date' | 'array' | 'object';
  required: boolean;
  description?: string;
}

Error Handling

try {
  const result = await processor.processInvoice({
    imagePath: './invoice.jpg'
  });
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Invalid API key provided');
  } else if (error.message.includes('image')) {
    console.error('Image processing failed');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Requirements

• Node.js 14 or higher
• Valid Mistral AI API key
• Supported image formats: JPG, PNG, GIF, WebP

License

MIT

Support

For issues and questions, please visit our GitHub repository.