What if the app operated on your behalf instead?

For a long time, a simple idea has been forming in my mind. What if the application has its own email address, and you can just forward it files, messages, and instructions for whatever you need done? This is entirely possible with standard tools that are easy to set up and consistently reliable.

The simplest version of an agent is an email

The word “agent” has accumulated a lot of noise. Strip it back to first principles and an agent is just a system that receives intent, decides what to do, and acts. Email fits that definition perfectly. You express intent (the message), attach context (the files), and the system does the rest.

Give your application its own email address. Then users can forward files, attach instructions, and send requests to that address. The system receives, authenticates, processes, and completes the work in the background. The user never logs in.

I built this for a commission management platform that insurance firms use. Every month, firms receive new commission data files from their providers. These files carry inherent parsing complexity: new agents, changed rates, structural inconsistencies between providers. Historically, a user would log in, upload the file, wait for parsing, review errors, and manually resolve each one. The entire workflow required the user to sit inside the app.

Now they forward the file to an email address and move on with their day.

The system parses the files through production Python parsers, validates the data against existing records, flags anomalies, and stores everything. If the agent needs clarification (an ambiguous agent name, a rate that doesn’t match any known structure) it replies to the email thread and asks. The user responds when they have a moment. The loop continues until the work is complete.

The entire interaction model is: send email, receive confirmation or follow-up question, done. This is identical in shape to how you work with a human colleague. The difference is that this colleague is perpetually available, never forgets context, and processes files in minutes rather than hours.

The architecture is four ordinary components

The infrastructure behind this is deliberately boring. Nothing here is novel. That is the point: the value is in the design pattern, not the technology.

First, an email domain. This can be your app’s existing domain or a simple subdomain. It receives inbound messages and routes them to a worker for processing.

Second, a worker. This is the first thing that touches an inbound email. It authenticates the sender against an allowed-senders table (one row per authorized address, with metadata for audit trails). If the sender is not recognized, the email is dropped. No ambiguity. If authenticated, the worker extracts attachments, parses the message body for instructions, and routes everything to the correct storage and processing pipeline.

Third, a backend API. This runs deterministic processing: the production parsers that handle commission files, validation logic, data storage. No LLM in this layer. These are the same parsers that would run if the user uploaded the file through the app’s front end. The trigger is different; the processing is identical.

Fourth, a sandboxed agent environment. Once deterministic processing completes, the API triggers an LLM agent in a sandboxed environment. This agent handles anything requiring judgment: interpreting what changed in this month’s file compared to last month, configuring new rates for a new period, responding to freeform instructions the user included in their email. The sandbox is synchronous with the API call, meaning the output is streamed back and verified before anything is committed. The timeout is generous (thirteen minutes) because rigor matters more than speed here.

The agent can send follow-up questions back through the email thread. This creates a genuinely asynchronous collaboration loop. The user is not waiting on a loading spinner. They sent an email, and they will get a response when the work is done or when a question needs answering. Just like working with a person.

Reason from first principles about where your interface lives

Every app has one central function. One reason someone uses it, the core value proposition of your tool. The question worth asking before you build any interface: does that function require a custom screen, or could it travel through a channel the user already inhabits?

This is where most software gets it wrong by default. We build login pages, dashboards, navigation bars, settings screens. We build these because that is what apps look like. But “what apps look like” is convention, not principle. The presentation layer should be derived from the nature of the core function and the habits of the user, not from what other apps happen to do.

Two valid design paths exist.

The first: your tool is delivered through a bespoke interface that genuinely increases the quality of the experience. A design tool needs a canvas. A code editor needs syntax highlighting and a file tree. A mapping application needs a map. In these cases, the interface is inseparable from the value. The custom UI is not overhead; it is central to the product.

The second: you conform as closely as possible to the user’s existing workflows. If the core function reduces to “receive input, process, return output,” then the interface is a delivery mechanism, not a product. Here, the highest-leverage move is to meet the user where they already are.

Both are correct. The nature of your core function decides which path is natural. But most apps default to the first path without ever seriously considering the second. They build a full interface because that is what you do when you build an app. The result is that users must learn and operate a custom tool for a function that could have been an email.

The test is straightforward. Does your user prefer giving text instructions over clicking buttons? Do they already communicate the relevant information through email or messaging? Is the core value in the processing, not in the interaction with a screen? If the answer to any of these is yes, wrapping your core function behind an email address is not a limitation. It is a higher-leverage interface than anything you would build custom.

The real value is background processing

The deeper point is not about email as a protocol. It is about when work happens relative to the user’s attention.

In a traditional app, processing is synchronous with the user’s session. You upload, you wait, you review, you fix, you upload again. Your attention is locked to the app for the duration of the work. The app cannot do anything without you present.

With an email-triggered system (or any async system), the entire processing pipeline runs in the background before the user ever considers opening the app. For commission files with inherent parsing complexity, this matters enormously. The validation, anomaly detection, and initial resolution all happen between the moment the user hits send and the moment they next check their inbox. By the time they look, the work is either done or a specific question is waiting for them.

This is the difference between operating a tool and delegating to a teammate. You do not sit next to a colleague and watch them process a spreadsheet. You hand it to them, explain what you need, and check back later. The email-based agent design creates exactly this dynamic.

This generalizes beyond commission files

The pattern is simple enough to apply anywhere the core function is receive, process, return.

Consider a research assistant. You forward an email with a topic and constraints. The system runs deep research: searching, reading, synthesizing. Hours later, a finished report arrives in your inbox as a PDF or a link to a hosted page. You never opened an app. You sent an email and received a deliverable.

Consider an accounting tool. You forward receipts throughout the month, one email at a time or batched. At month end, you send a message: close the books for March. The system categorizes, reconciles, and produces a summary. The entire interaction happened inside your inbox.

Consider a document review system. You forward a contract. The agent reads it against your standard terms, flags deviations, and replies with a structured summary of what needs attention. You respond with approvals or questions. The negotiation prep happens through a channel you check thirty times a day anyway.

In each case, the same structure holds. The email is the trigger. The backend does the work. The inbox is the interface. The user never has to learn a new tool, navigate a new layout, or remember a new login.

Email is the most underexploited interface in software

Email is a powerful and completely generalizable channel that every professional already uses. Instead of fragmenting services into custom interfaces, consider whether your core value could travel through a channel your users already live in.

The strongest argument for this design is not technical. It is behavioral. You are not asking users to change how they work. You are not asking them to adopt a new tool, learn a new interface, or build a new habit. You are inserting your service into a workflow that already runs every single day. The friction drops to near zero because the interaction model is one the user has practiced for decades.

This is what making a tool feel like a teammate actually means. Not a chatbot inside your app. Not a sidebar with a language model. A system that receives work through the same channel you use to communicate with every other person in your professional life, and delivers results the same way.

Always reason from first principles when you build a user interface. Too many of the interfaces you and I encounter are conventional without being thoughtful. The presentation is what makes or breaks the experience. If your app’s core function can travel through email, give it an email address.

But letting an agent have a full connection to your database is dangerous for obvious reasons. Agents can accidentally alter data without permission. So the challenge is: how do you give an LLM the full read picture while air-gapping it from accidental writes?

The answer is two connection strings.

All Commission Data Through One Agent

I built a platform for managing commission distribution at insurance firms. Sales, employees, agents, products, all in one Postgres database. Users manage commission flows from carrier to sales agent. The platform handles a dense stream of data: commission rates, agent information, performance analytics.

Users can navigate the UI manually. But the full capacity unlocks when an LLM agent works on behalf of the user. A task like migrating a commission rate across every configured agent, painful in a spreadsheet, trivial for the agent.

The system needs three foundational pieces to make this work.

Schema, Strings, and a Map

First, a schema that fits the application. Different apps need different schemas. An ecommerce store is fundamentally different from a commission distribution system, so the way you schematize your database is a contained problem for your specific app.

Second, two connection strings. The first is a read-only replica. This is the string the LLM uses for all queries that are not approved edits. The second is a standard connection string with write access, gated behind explicit human approval. This separation is the core of the design. It guarantees the agent can never run edits without approval, no matter what it generates.

Third, a continuously updated plain-text artifact of the schema, a markdown document describing every table, column, and relationship. This is what allows the LLM to instantly understand your specific database and write correct SQL against it. Without it, the LLM makes dumb errors.

Query Without Risk

Here’s how a query flows through the system. The user asks a question in a chat interface:

“What does sales amount to in January?”

The agent receives the question, references the schema artifact, and writes a SQL command:

psql "$SANDBOX_DB_URL" -c "SELECT SUM(amount) FROM sales WHERE date >= '2024-01-01' AND date < '2024-02-01';"

The agent executes that command against the read-only connection. The database returns:

    sum    
-----------
 452839.50
(1 row)

The agent then writes the response in plain language:

“Sales in January totaled $452,839.50.”

The full loop (receive question, write SQL, execute, return answer) takes roughly ten seconds. Each step is one LLM call. The agent receives the user question and writes the SQL. The database result triggers a second call, now containing the returned data. The agent then decides: retry with a different query, or write the final reply.

Writes Only on Approval

Now for the dangerous part: edits.

When a user asks for an action that requires modifying data, the agent runs through the same loop but against the read-only string. The system identifies when the generated SQL contains a write operation (INSERT, UPDATE, DELETE), blocks it from executing, and surfaces the proposed SQL in the user interface for explicit approval.

Only on human approval does the system switch to the standard connection string and execute the write.

This is a simple design, but it’s the most effective one I’ve found. The read-only replica makes it physically impossible for the agent to alter data during its reasoning and exploration. The approval gate on the write string means edits only happen with informed human consent. Two connection strings, one architectural guarantee: the agent cannot break what it hasn’t been allowed to touch.

Restriction Makes Agents Dumb

LLMs are probabilistic machines. They can generate completely random, potentially harmful SQL. The instinct is to restrict their access: limit what tables they can see, constrain what queries they can write. But restriction makes the agent dumber. It loses context. It can’t answer questions about data it can’t see.

The better path is full read access with an air-gapped write path. Let the agent see everything. Let it explore, join, aggregate, analyze. Then gate the single dangerous action, writing, behind a human checkpoint. You get the full intelligence of the agent without the risk.

In this article, I walk through a specific data flow from the insurance distribution business to present a framework for thinking about how data becomes useful. The goal is to make the example concrete enough that you can infer the key concepts and apply them to your own work.

Data Stuck in Spreadsheets

Inside the insurance distribution business, there is a vast information flow where sales, products, and commissions are transported through multiple steps. This data is communicated and shared inside spreadsheets, which are inherently difficult to work with in bulk.

The problem, stated simply: get the data out of the spreadsheets, clean up the structure, and funnel the data into a structured, queryable database like Postgres. What we end up with is a database that gets hydrated with new data at each period interval — data we can then work with downstream. Finding out who sells the most, what is selling the best, what products have a bad clawback rate, and more.

The goal of cleaning the data into a database is to create a single source of data truth. All data conforms to the same structure, allowing us to use the data stream inside our models to get insights.

An analogy: imagine buying a bag of M&Ms. You expect every piece of candy to conform to a specific shape, weight, and taste. But each piece has a different color. Now apply this to transforming spreadsheets into our database format. We build a transformer that reformats the data into our desired shape and form, but we retain the key value of each data point. We keep its colors intact. When we scale this across tens to hundreds of spreadsheets, this becomes critical. If even one source has been parsed incorrectly, our models lose accuracy. Uniform shape lets us compare the colors.

One Schema for All Sources

For our insurance data flow, I am working with commission spreadsheets. Each spreadsheet has a different structure because each source is a different insurance carrier, each with different data systems. The most important task is to retain high resolution from each data source while transforming it to conform to our uniform schema for commission data.

The transformation is done with a Python backend written specifically for each commission type, which transforms the source to fit our uniform schema. For maximizing convenience, I have built the entire backend in the cloud: when users have new files, they simply forward an email to a custom address (with the spreadsheet files), which triggers the system to validate, transform, and store the data into the database. From there, the next chunk of work can be initiated immediately.

My goal as a systems engineer is to make purely necessary steps — like the data transformation — blend into the background. Make them as unnoticeable as possible so the app experience does not feel like another spreadsheet.

It is helpful to revisit and iterate in circles: how we transform the data, what models we want, what interfaces will be used. Continuously go around again, modifying the way we transform data so that we have the necessary inputs downstream. Some data sources will not meet all requirements for our schema. This is fine. We build dedicated models into the transformation phase to either enrich the data with additional metadata, or create ways of grouping temporal data to conform to our schema.

Inference from Clean Data

Once the data has been transformed and stored, the creative part begins.

A model is how you take stored data from the database and infer something from it. The word infer — to deduce or conclude information from evidence and reasoning rather than from explicit statements — closely aligns with the overarching goal of working with data. We should spend time making sure we have a solid model, so that from there we can infer valuable information.

Each model should tailor to a specific desired output. For the commission data flow, we want to understand the different products that are selling, and quantify them over different temporal spans. Breaking this into a pseudo-spec: I need the product rows, some way of identifying different product types, and temporal metadata about the time interval each record belongs to.

The Interface Layer

The second category is the interface: where our model is presented to the user so it makes sense to them, meeting them where they are so they can understand and make decisions with the data.

An interface is a point where two things meet and interact. The overarching purpose is to be the portal for the user into accessing all of their data maximally. Maximally means the models should be customizable, interactive, and not static.

If the user gets an idea of how they would like to query the data, the interface must meet that demand.

I believe there are currently two key forms of interfaces: natural language, and user-configurable modules. The example interface uses a combination of the two — leveraging the strengths of the modular configurable interface, and enhancing it with the simplicity of natural language. Language is used to orchestrate what you want. The modular interface is used to display it.

Tables That Breathe

The interface is built with a hybrid of the accessible table-like design where content is displayed in a familiar spreadsheet way. Taller row heights and spacious column layouts are conscious decisions to make the spreadsheet visual a friendlier interface compared to a high-density spreadsheet. The overarching goal is to replicate the user’s familiarity with a table while reducing the energy needed for comprehension. A natural next step would be visual representations of the underlying model, perhaps clear visuals comparing and differentiating the data as graphs.

Natural Language Interaction

This is where the power comes in. Instead of the traditional model of a spreadsheet with columns, rows, sorting, and filters, natural language introduces higher resolution of intent. The user explains their desired outcome in their preferred language, rather than conforming to the rules of a spreadsheet.

Speed follows from this. Instead of the human manually configuring filters and rules, the underlying system can figure out user intent and build a model of the desired output at the speed of a hundred words per second. The difference in time spent compared to building the same view in Excel or Google Sheets is stark.

An example: a user might want to see all car insurance products from March to August with commission to agent under $100. Imagine the work of doing this across thirty-plus Excel files. But from the exact line of text — “all car insurance products from March to August with commission to agent under $100” — here, there is plenty of signal inferable for an intelligent system. Our example interface creates the view within seconds from synthesizing the user intent into a model. The user does not need to know any code, only a language.

For practical use, the users can download their view into an exported file PDF or Excel. This allows them to take the data further, into whatever work they are doing. Familiar formats win here because they make the data portable and easily sharable.

How It Works: SQL Under Natural Language

The LLM is the interpretation layer that receives the user intent, reasons over it, then begins an iterative process where it creates — through trial and error — the data model that satisfies the request. The interpreter returns the final data model back to the user interface for instant preview. A complete iteration takes less than thirty seconds.

An LLM most commonly refers to a Large Language Model, a type of Artificial Intelligence (AI) trained on massive amounts of data to understand, generate, and process human language.

Because of our heavy work upstream on clean and structured data, we have a perfectly predictable data source structure, as a result of our transformation, at this point in the pipeline. No matter the number of rows, the system iterates in seconds because of how the architecture is built.

The power here is the power of Postgres and SQL. Our LLM interpreter reads the user intent and writes SQL queries that shape our data model. Think of SQL like a language for prescribing data recipes: you write explicitly how to make a specific data dish. A recipe for making pizza scales no matter how many pizzas you make. SQL follows the same principle: no matter how much data you have, the recipe scales.

PostgreSQL (often shortened to Postgres) is a free, open-source object-relational database management system (ORDBMS). It is widely regarded as one of the most advanced and reliable database systems available.

SQL (Structured Query Language) is the standard programming language used to manage, query, and manipulate data within relational databases. It organizes data into structured tables with rows and columns, functioning as a sophisticated system for handling large volumes of information far beyond the capacity of traditional spreadsheets.

Beyond Commissions

The fundamentally interesting value of this interface is that it enables complete accessibility for any non-technical user to explore vast amounts of data. A few examples:

• Teachers with data about students and grades

• Accountants searching for specific receipts

• Researchers reviewing data quality

• Library inventory databases

• SaaS revenue analytics

• Investor modelling for capital allocation

Most data tools today assume a level of user expertise. I wanted to challenge that assumption. Instead of expecting the user to configure the system, why not let an AI do it? I believe this is the correct vision. The LLM becomes the configurator and the interpreter interface between raw human intent and structured data operations.

This interface is still in its infancy. There are many ways to improve the models, the interface design, and most importantly the accuracy of the LLM agent. At the boundary of any new technology, there is always a wide range of work to be done before the full value can be harvested. That is what makes it worth building.

Reading PDFs is a vital function of any application dealing with documents. Financial documents are commonly stored as PDFs (portable document format) because of the format’s permanent nature and simple storage. PDF is a great format for humans. It has a natural print layout and an easy-to-digest way of structuring text content.

But one of the bottlenecks of PDFs is their difficulty of utilization by computers or intelligent systems such as LLMs. PDFs are best when “looked at”, not when they are parsed by a machine. The analogy is clear: the PDF is for humans, not for computers.

Reality has it so that for more than a decade, PDFs have been the de facto standard for storing key information such as reports, accounting ledger summaries, information transfers, and more. This poses a challenge to anyone building a system that leverages PDF ingestion as part of its components.

In this article, I propose a three-step process for dealing with PDF files, and parsing key information from them, in a high-stakes financial system.

Setting the Scene

I have worked for over a year on a component of a system that deals with financial matters like thousand-plus row files for commission records. A common file size is 107+/- page PDF documents. The requirement is perfect extraction quality of key financial data points, which then get ingested into a downstream calculation component of the overall system.

Through trials and evaluations of parsing techniques, I have landed on a solution which I have complete trust in. Today, I will be sharing this system in depth.

Defining the Inputs and Outputs

In any system, defining the interfaces for each component makes data flow between components a smooth matter. Starting with the parsing requirements for the PDF parsing component is one of the most important decisions you make. Clearly defining the input and output requirements helps you reduce the inherent noise of data. Knowing exactly what you need from a file is the first step.

For this system, the PDF parsing component is required to output the following key data points:

• Agent number -- The identification of the sales agent from whom the parsed sales row is linked to

• Sales id -- Sales row identifier, for example, Sales #12345abc

• Product id -- “Car insurance, #999”

• Commission base -- The base amount, from which commission downstream gets computed with Python

• Commission amount -- Occasionally, the commission is pre-computed in the source file

• Period id -- Crucial identifier required in order to accept a sales row

• Commission rate -- Occasionally the rate is explicit in the source file

Having defined the exact data I need from a PDF, I can go about the business of building the parsing. Knowing exactly what I am after allows me to build a schema into the system that can be validated for each output of the parsing component. This prevents bad data from ever reaching the downstream components. Additionally, I can reject files up-front: if the files are not compatible with the required output (i.e., if the PDF is a news article or something unexpected), the parsing cancels immediately instead of initializing a full “dead” run.

Once I know clearly what I expect from this component, I can progress into designing the rest of the system.

Parsing Signal from Noise

Parsing PDF files is one of the most delightful problems in software systems. Inherently, the task of getting information from a PDF is all about extracting a clean signal (a specific data point) from the random and high-entropy nature of PDFs (unlimited formatting variations possible).

I favour three different parsing methods and services. Let’s walk through each one, keeping in mind our schema and output requirements.

Mistral OCR API

The Mistral OCR API is a fast and reliable OCR machine learning model service where a user can ingest a PDF file of any form and sort, and get a structured output in markdown (plain text format without any formatting or styling) or JSON (JavaScript Object Notation). Both of these output formats are easy to parse and read by a computer, because both get rid of any unnecessary styling, metadata, and formatting, leaving you with only the words, text, and numbers.

The Mistral OCR API is a favourite of mine because of how fast you can go from zero to working system. The service allows large batch uploads and completion within seconds.

Thinking about how the Mistral OCR service fits into the system: the API allows you to parse any PDF, extract tables, get images, and extract the entire PDF contents into the two much cleaner formats mentioned.

From here, the clean and simple output is ready for the next step in the system, which I will talk more about below.

Mathpix

I believe in redundancy as a key property of any system, deeply integrated into the design from the very first initialization. This is why I choose to have an additional OCR-based service in utilization -- not just as a fallback for Mistral failures, but in synergy with Mistral. Mathpix is fundamentally different from Mistral in that it leans more heavily towards maths and tables. This is perfect for a financial system that requires complete accuracy. And, doing the maths on the probability of system failure, adding a second OCR tool exponentially reduces the probability of complete failure.

Mathpix is similar to Mistral in that you can upload a PDF and receive a structured, plain-text version of the PDF contents.

Getting specific: inside the Mathpix API there is a rather “hidden” boolean you can enable: enable_tables_fallback=true. This option enables what Mathpix calls “an advanced table processing algorithm that supports very large and complex tables.” Thinking back to what our schema requirements are, and the types of files our PDF parsing component handles, enabling this option is a no-brainer for our 100+ page table-heavy files.

PDF to PNGs

To further bulletproof the system, I leverage the tool pdftoppm -- a CLI (command line interface) tool that runs locally to convert a PDF file into one PNG image screenshot per page. This is a very high-leverage tool in this system. The two previous parsing services allow us to rapidly extract the text and image content of the input files, but pdftoppm allows us to do further and more rigorous analysis of each page and its original structure.

From the command below, I get one PNG image per page, from where the system can easily review the specifics of each page:

pdftoppm -png -scale-to 1800 input.pdf output

-scale-to 1800 constrains the output image resolution to maximally 1800px on the tallest side, useful for consistency and for downstream API ingestion limitations which we will get to.

Putting It All Together

So far, I have talked about how to get information from a PDF file into a “friendly” format, more simply readable and understood by a computer. Once these parsers have done their job, we have the following pieces to work with:

• Mistral: cleaned markdown or JSON including extracted images

• Mathpix: clean markdown with additional “advanced” table extraction for edge cases and superior coverage for table-heavy files

• pdftoppm: one PNG screenshot per PDF page for deeper visual analysis of the original page structure

Orchestrating the Parsers

With these three parsed versions in hand, we can now orchestrate agents to do the inference of data from the PDF source file. We leverage a visual and text-based LLM model inside a sandbox running in the cloud to do this work, using the two current best tools for the job:

• Claude Agent SDK in Python

• E2B sandbox pre-built templates

Claude Agent SDK is a very powerful tool for processing data and getting a specific output. Once installed, the Claude Agent SDK bundles Claude Code’s claude tool, which is the current best coding and computer agent available. Additionally, using Claude, you instantly get access to the best LLM models on the market.

E2B is a service for spawning ephemeral small virtual machines in the cloud. A virtual machine is like your desktop computer, but on a smaller scale and for a different use case. When using an E2B sandbox, we can allow the Claude Agent to do virtually anything to “its sandbox”, because the only thing that matters is not what the agent does inside the sandbox, only what it produces and outputs from the work done inside of it.

Think of the sandbox as the “workshop” where the LLM has a range of tools (such as the three parsers we have talked about, and Python) and where it can break things, run experiments, and do virtually anything, without ever touching our application production code.

Instructing the Agent

Now that we have laid the foundation of the environment, we can begin instructing the Claude Agent on what we desire it to do. Here, we revisit the schema we defined earlier -- agent number, sales id, product id, commission base, commission amount, period id, and commission rate. These are the exact fields we need from any given PDF file, and they form the foundation of the instructions we give to the Claude Agent in the form of a formal document inside the sandbox -- the agent’s “work requirements.” This formal markdown (.md) document is similar to a document you hand to a co-worker when you need them to do a particular thing. The fewer questions the Agent might have about your document, the better the document is.

Think of this as the specific instructions covering:

1. How the agent will work. Exactly what steps it should take.

2. How the agent will create the output. Exactly how the desired output should look (use the schema rigorously).

3. What are common issues and things to know? How does the agent deal with failure? (i.e., if the file is not a financial document, or if a part of the system breaks)

These three points form the basis of a document which will be iterated on countless times through tests until the Claude Agent produces deterministically quality outputs. The Claude Agent is an LLM AI model, which means that the more specific and helpful you as the creator can be through the instructions, the more flawlessly the Agent can do the work for you.

Let me now outline how the Agent will do the work. I will not bore you with the full instructions, as these get long and specific for the system design requirements. By nature, your system will be of differing design, requiring a different set of instructions. But the following outline creates a high-quality, predictable set of examples you can build on.

Introduce how the component (the agent + sandbox) fits into the system:

• “You are reading a pre-parsed PDF file containing financial information.”

• “You are a component part of a larger system processing commission sales records using Python for calculation.”

• “Your task is to produce high-quality JSON extractions of a PDF file.”

• “The JSON file you write is used downstream inside the next system component to store and do Python calculations on. Doing any calculation with the data is NOT your task.”

Introduce the system environment:

• “You have three directories, each containing different parsing versions from the same file.”

• “Use all three directories to produce the final JSON parsing of the sales rows containing complete verbatim-JSON-transformed extractions from the source file.”

• “Use all three parsing versions in order to cross-verify the parsing of the file by processing each page in logical, self-determined chunks. Using all three parsing versions gives you a completely verifiable way of working, which is perfectly necessary for the complex financial data you are working with.”

Define the expected output requirements and where it should be produced:

• “You will be validated using programmatic JSON validation that the final JSON file you write is valid. Therefore, follow the assigned JSON schema rigorously.”

• “If you realize that the PDF source file will not be compatible with the assigned JSON schema, you simply escape and fail instantly. Failure is accepted if the file is clearly incompatible -- in fact, failure is desirable in such a scenario.”

• “All final JSON outputs must be written to a file called output.json inside the output directory in your file environment.”

Explain how to work and the minimum amount of verification until confidence can be produced:

• “Given the three versions of parsing, you should use all three versions iteratively to verify your inference of the data. This allows you to keep the data quality high.”

How to deal with large samples:

• “By running the tool estimate_tokens.py you can instantly get a recommendation as to how you can work with the assigned files. If the tool output is over the red line, you must spawn a team of agents and assign work specifically, with perfect overlap, and create rigorous validation for the final end product written to the output directory.”

• “Each agent writes their own JSON files, from where you do the merging once ALL data has been processed. If a part of the data fails, or you get stuck somewhere, you must fail quickly instead of trying to fix a massive run.”

How to deal with failure gracefully:

• “Simple failures are tolerated and should simply be ignored. For example, a tool use failure or similar -- if this happens, simply write your own tools on demand.”

• “Be flexible with the approach, but rigid in the output.”

Specific first steps:

• “Start first with checking the size of the assigned work. This will inform whether you can do the work alone, or if you need to spawn an agent team.”

• “Always prefer creating an agent team, versus using sub-agents, when it comes to specifically dealing with writing outputs and processing files.”

Making It Work

The above system is a result of trying and experimenting with countless approaches to the problem of dealing with PDFs. I believe this system produces a predictable and satisfactory solution.

In integrating this into the overall system, I have had success processing high-risk financial information like commission data with accuracy. Dealing with, and handling the risks of, inaccurate or false data extraction is my worst nightmare. Hence, this system design aims to eliminate such risks through cross-verification, frontier LLM models, and validations.

Because of the nature of PDFs, it is impossible to create a perfectly deterministic solution when one does not know what the PDFs will look like. The system above is designed specifically to solve the requirement of being able to read and process any incoming PDF containing financial data. Once tested to a sufficient degree, and error-corrected through iterative design as per your system requirements, this system delivers a satisfactory result.