AI Training & Customization
Improve field-level AI accuracy for specific forms through a structured fine-tuning process
Overview
When a form is added to Instafill.ai, it can be submitted for AI fine-tuning. The system first checks whether fine-tuning is already in progress for that form to prevent duplicate runs, then initializes a training status record and begins processing the form page by page, tracking progress after each page completes.
Free-tier workspaces process only the first two pages of the document. Once the main fine-tuning run finishes, post-processing tasks execute asynchronously to sync updated field data back to the form record.
A key architectural detail: fine-tuning results are tied to a field-based hash computed from the form's field structure. If two users upload identical forms — such as a W-9 or I-9 — they share the same hash, so fine-tuning applied to one propagates to all copies across all workspaces that reference that hash.
Key Capabilities
- Duplicate-Trigger Prevention: Before queuing a form for fine-tuning, the system checks whether fine-tuning is already in progress for that form hash, preventing redundant processing
- Page-by-Page Progress Tracking: The training status record updates after each page, so the UI can report partial progress on long forms
- Free vs. Full Tier Processing: Free-tier workspaces process pages 1–2 only; paid tiers run fine-tuning across all pages
- Post-Processing Hook: After the main pass completes, post-processing tasks run asynchronously to sync updated field hints to the form record
- Hash-Based Propagation: Fine-tuning outcomes sync across all forms sharing the same field hash, so popular government forms (W-9, I-9, CMS-1500, W-4) benefit from community fine-tuning without reprocessing
- Status Tracking: The training status record tracks fields total, fields processed, cost, duration, and version — with a flag indicating whether only the first two pages were processed (free-tier runs)
- AI Prompt Observability: Every AI prompt issued during fine-tuning is logged for debugging and cost attribution
How It Works
Trigger Fine-Tuning: A form owner initiates fine-tuning from the form detail page. The system performs a duplicate-trigger check before proceeding.
Initialize Status: A training status record is created indicating the run is in progress, with the total field count set and processed count starting at zero.
Page Processing: The system iterates through each page. For each page, the AI receives the field layout and surrounding text context, then generates improved field recognition hints. The processed count increments after each page.
Free-Tier Limit: If the workspace is on the free plan, only pages 1 and 2 are processed. The training status record indicates this is a partial run.
Post-Processing: After the main run, post-processing executes asynchronously to sync updated field data back to the form record and trigger any downstream cache invalidation.
Status Resolution: Training status is updated to completed on success or failed if an unrecoverable error occurs. The record also captures cost, duration, and version for audit purposes.
Hash-Based Sync: Because fine-tuning outcomes are keyed by field hash, identical forms shared across workspaces (e.g., the IRS W-4 or USCIS I-485) receive the improvement without each workspace needing to re-run the process.
Use Cases
Fine-tuning is most valuable when the default AI extraction produces systematic errors on a particular form type. A medical billing operation processing CMS-1500 insurance claim forms might find that the AI consistently misreads the NPI field or conflates box 21 (diagnosis codes) with box 24D (procedure codes); fine-tuning on a sample of correctly labeled claims corrects this pattern for all future sessions. A law firm using I-485 adjustment-of-status applications can fine-tune so that the AI correctly distinguishes Part 1 (applicant information) from Part 9 (biographic information) without manual field remapping. For W-9 forms processed in high volume, fine-tuning ensures TIN type (SSN vs. EIN) is detected from checkbox state rather than inferred from text context.
Benefits
- Targeted Accuracy Gains: Fine-tuning focuses on the exact fields causing errors in your forms, rather than retraining a general model
- Shared Improvement for Common Forms: Government forms like the W-4, I-9, W-9, and CMS-1500 benefit from fine-tuning performed by any workspace that shares the same field-hash, reducing per-workspace cost
- Transparent Progress: The training status record gives real-time progress on large multi-page forms — fields processed out of total fields
- Free-Tier Access: Basic fine-tuning (first two pages) is available on the free plan; full-document fine-tuning requires a paid plan
- Auditability: Every fine-tuning run records cost, duration, and version in the status record, and individual prompt calls are logged for observability
Security & Privacy
Fine-tuning runs are scoped to a specific form identified by its field hash. All data is workspace-scoped and protected by JWT authentication middleware across all service layers. A workspace can only initiate fine-tuning for forms it owns; the hash-based propagation shares field recognition improvements, not document content or filled data. AI prompt logging captures prompt structure and token counts but does not store the user's actual form field data.
Common Questions
What does the training status record contain and where is it visible?
The training status record contains:
- Status: In Progress, Completed, or Failed
- Type: Automatic (system-initiated) or Manual (user-initiated)
- Fields total: Total number of fields detected on the form
- Fields processed: Fields processed so far (updates per page)
- Cost: Estimated token cost of the fine-tuning run
- Duration: Wall-clock time in seconds
- Version: Incremented integer tracking which fine-tuning pass this is
- Partial run flag: Indicates whether only the first two pages were processed (free tier)
The form detail page in the UI reads this record to display a progress bar during active runs and a completion summary afterward.
Why does fine-tuning on one workspace's W-9 improve results for another workspace?
When a PDF is processed, a field-based hash is computed from the form's field structure. Two uploads of the same W-9 produce the same hash. Fine-tuning outcomes are stored against this hash rather than against a workspace-specific form ID. Consequently, when the system resolves field recognition hints at fill time, it retrieves the best available hints for that hash — regardless of which workspace originally ran the fine-tuning. This architecture means heavily-used government forms accumulate community fine-tuning over time without each workspace paying the full processing cost.
What happens if fine-tuning fails partway through?
If an error occurs during page processing, the training status is updated to Failed. The fields processed count reflects how many fields were processed before the failure. Pages already fine-tuned are not rolled back — partial improvements are retained. The form remains usable for filling sessions; it simply continues using whatever field hints existed before the failed run. A new fine-tuning job can be triggered manually from the form detail page to retry.
Does the free-tier two-page limit affect accuracy for longer forms?
Yes. Free-tier processing covers only pages 1 and 2, so field recognition improvements apply only to those pages. For a form like the I-485 (20+ pages), pages 3 onward use the base AI model without the fine-tuned hints. The training status record indicates this is a partial run. Upgrading to a paid plan enables full-document fine-tuning across all pages, and the status will reflect the correct total field count across the full document.
How are AI prompt traces used after fine-tuning?
Every AI prompt issued during a fine-tuning run is logged for observability. Each trace captures the prompt template, input variables (field name, surrounding text, page number), the model response, token counts, and latency. The engineering team uses these traces to identify which field types are producing low-confidence outputs, diagnose prompt regressions across model updates, and attribute token cost to specific form types. Traces are not exposed in the end-user UI but inform ongoing prompt improvements.