Best Practices & Troubleshooting

Best Practices

Adapter Selection

• Use a capable VLM as the advanced LLM (GPT-4o, Claude Sonnet, Gemini Pro). Table extraction accuracy depends heavily on the model's vision and reasoning capabilities.
• Use a fast, inexpensive model as the lite LLM (GPT-4o-mini, Claude Haiku, Gemini Flash). Agent 1 makes one call per page, so cost adds up on large documents.
• Ensure your X2Text adapter produces clean text. LLMWhisperer is recommended for PDFs with complex layouts.

Prompt Writing

• Focus the target table description on what makes the table unique — its title, column headers, location in the document, or the type of data it contains.
• Test with a few representative documents before processing in bulk.
• When your document has multiple tables, clearly distinguish the target table from the others.

Page Range Optimization

• Narrow the Start Page / End Page range when you know where the table appears. This reduces the number of pages Agent 1 screens and the overall cost.
• For recurring document types (e.g., invoices from the same vendor), set the page range once after checking a few samples.

Parallelism

• Start with the default parallelism of 4 and increase only if processing is slow on large documents.
• Monitor your LLM provider's rate limits — high parallelism with a rate-limited API key can cause failures.

JSON Structure Design

• Keep the JSON structure simple and flat when possible. Deeply nested schemas are harder for the code generator to map correctly.
• Use clear, descriptive field names that relate naturally to the table columns.
• For grouped output, define a nested schema where the group-level fields sit alongside an array of child items. The extractor infers grouping from the schema shape — no separate setting is needed.
• When using summary totals, place the summary object at the same level as the child items array so the extractor can compute aggregate values per group.
• Test the JSON structure on a few documents before using it in production pipelines.

Multi-Page Tables

• The extractor automatically merges rows that span page breaks. If you notice split rows, verify that the row identifiers (first column values) are consistent across pages.
• For very long tables (100+ rows), consider whether all rows are needed or if the page range can be narrowed.

Limitations

• VLM-dependent accuracy. Extraction quality depends on the advanced LLM's vision capabilities. Some models handle complex table layouts better than others.
• Complex merged cells. Tables with extensively merged cells (spanning multiple rows and columns) can reduce extraction accuracy.
• Handwritten tables. Handwritten or heavily stylized tables are not well-supported. The pipeline works best with printed, digital-native tables.
• Sandbox restrictions. The code executor (Agent 5) has limited module access. Transformations requiring specialized libraries (e.g., pandas, numpy) are not supported.
• 60-second timeout. Generated transformation code must complete within 60 seconds. Very large tables with complex transformations may exceed this limit.
• Cost. The multi-agent pipeline makes multiple LLM calls per document. For simple tables, standard table extraction (enforce_type: table) is more cost-effective.

Troubleshooting

No tables detected

Possible Cause	Solution
Page range excludes the table	Widen Start Page / End Page range or set End Page to 0 (all pages).
Lite LLM is too weak	Switch to a more capable model for the lite adapter.
Target table description is too vague	Add specific details about the table (title, column headers, location).
Document quality is poor	Use a higher-quality scan or a better X2Text adapter.

Missing rows or columns

Possible Cause	Solution
Rows split across page breaks	The extractor merges these automatically. If rows are still split, check that identifiers match across pages (case-sensitive).
Table is very wide	Some VLMs truncate very wide tables. Simplify the JSON structure to focus on essential columns.
Faint or low-contrast text	Improve document quality or use LLMWhisperer with force text mode.

Inconsistent results across runs

Possible Cause	Solution
LLM non-determinism	Run extraction 2–3 times and compare. If results vary significantly, try a different advanced LLM.
Ambiguous prompt	Make the target table description more specific.
Code generation variability	Add explicit mapping instructions to reduce ambiguity for the code generator.

Slow extraction

Possible Cause	Solution
Too many pages being scanned	Narrow the Start Page / End Page range.
Low parallelism	Increase Parallel Pages in settings (up to 32).
Slow LLM adapter	Switch to a faster model or provider.
Large document with many tables	Focus the prompt on the specific table to reduce processing.

Related Features

• Look-Ups — Enrich extracted table values with reference data.
• Post-Processing Webhook — Send extraction results to an external service for additional processing.
• Combined Output — View combined output from multiple prompts, including agentic table prompts.