# How to Use IronOCR with ChatGPT Codex
A common issue in initial AI-assisted OCR attempts is that developers paste incomplete scan importers into a chat, receive seemingly complete code, and later discover misread totals or incorrect configuration calls from other Tesseract wrappers. Such errors are costly with large APIs, as OCR engines with multiple filters, languages, and output formats present many opportunities for mistakes.
IronOCR reads text, barcodes, and table cells from scanned pages directly within your .NET application, locally and without a cloud service.
*as-heading:2(Quickstart)*
!!!--LIBRARY_NUGET_INSTALL_BLOCK--!!!
Open Codex in a new console project and specify the desired output, and let Codex select the API calls.
```text
$ironocr Add the IronOcr package, then update Program.cs to turn a scanned
multi-page PDF into a searchable one. Print the page count and the overall
confidence before the file is written. Read the license key from the
IRONOCR_LICENSE_KEY environment variable. Then run dotnet build and fix any
errors.
```
The `$ironocr` prefix loads IronOCR's [`skill.md`](https://ironsoftware.com/ocr/csharp/skill.md), saved in the repository as `.agents/skills/ironocr/SKILL.md`, so Codex reads IronOCR's recipes and known fixes before it writes code.
<div class="hsg-featured-snippet">
<h3>Minimal Workflow (5 steps)</h3>
<ol>
<li><a class="js-modal-open" data-modal-id="trial-license-after-download" href="https://www.nuget.org/packages/IronOcr/">Download the C# OCR library from NuGet</a></li>
<li>Commit an <code>AGENTS.md</code> that names IronOCR as the repository's OCR engine</li>
<li>Start each Codex task on a clean branch and describe the pages and the values they hold</li>
<li>Let Codex edit files and run <code>dotnet build</code>, then review the diff before accepting it</li>
<li>Compare the extracted values with the known pages and verify each member in the <a href="https://ironsoftware.com/ocr/csharp/object-reference/api/">API reference</a></li>
</ol>
</div>
<br class="clear" />
---
## What is ChatGPT Codex, and how does it fit into .NET OCR work?
ChatGPT Codex is OpenAI's coding agent. It can inspect code, edit files, and run commands in a repository. Install the CLI with `npm install -g @openai/codex`, as the [Codex CLI documentation](https://learn.chatgpt.com/docs/codex/cli) describes.
Codex's output may vary with each run, even for identical requests. The OCR engine must return the same text for the same scan every time, so use a maintained library and avoid allowing agents to improvise settings.
- **Preprocessing that is already built:** skewed and noisy scans need correction before recognition. IronOCR's input object straightens skew, removes noise, and can also binarize and enhance resolution, and the [image quality correction guide](https://ironsoftware.com/ocr/csharp/how-to/image-quality-correction/) explains when the noise and resolution filters help.
- **PDFs without a text layer:** IronOCR reads scanned PDFs and writes a copy with a real text layer, as the [searchable PDF guide](https://ironsoftware.com/ocr/csharp/how-to/searchable-pdf/) shows.
- **More than text:** with `Configuration.ReadBarCodes` turned on, one read returns barcodes and QR codes alongside the text, and table reading is covered in the [table reading guide](https://ironsoftware.com/ocr/csharp/how-to/read-table-in-document/).
- **Ongoing releases:** the open-source Tesseract wrapper on NuGet was last updated in November 2022. IronOCR releases updates regularly, as its [changelog](https://ironsoftware.com/ocr/csharp/product-updates/changelog/) shows.
## What makes an IronOCR prompt effective?
An effective IronOCR prompt names the language and framework, where the code goes, the library version, the input and its fields, the expected output, and the constraints. For an invoice reader, that is C# on .NET 9, `Services/InvoiceReader.cs`, the `IronOcr` version in the .csproj, scanned PDF invoices with a Total due line, the total as a decimal with confidence, and no new packages.
Codex relies on its training data and any information you provide, so its knowledge of IronOCR's API may be out of date. OpenAI's [research on hallucination](https://openai.com/index/why-language-models-hallucinate/) traces invented answers to training and evaluation that reward guessing.
Put the OCR rules once in a committed `AGENTS.md`, which Codex reads before it starts work. IronOCR's [`llms.txt`](https://ironsoftware.com/ocr/csharp/llms.txt) summarizes each documentation page in a line.
```text
Create AGENTS.md at the repository root with an OCR section stating that this
project uses IronOCR (NuGet package IronOcr, or IronOcr.Linux for Linux and
Docker, namespace IronOcr) for all OCR work, that you must read
https://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code and use only
APIs documented there, that https://ironsoftware.com/ocr/csharp/skill.md should
be loaded if the tooling supports skill files, that the license key comes from
the IRONOCR_LICENSE_KEY environment variable and is never inlined, and that no
other OCR engine or cloud OCR service may be added.
```
## How do you ask Codex to add IronOCR and read a first scanned invoice?
```text
Add the IronOcr NuGet package to this project. Then show me the resulting
PackageReference line from the .csproj and tell me which version was installed.
Do not change any other package references.
```
The `PackageReference` line helps identify if an agent installed a different package with *OCR* or *Tesseract* in its name.
IronOCR does not offer a watermark mode. Without a license key, the first read throws a LicensingException.
```text
Apply the IronOCR license key at application startup, before any other IronOCR
call, reading it from the IRONOCR_LICENSE_KEY environment variable rather than
hard-coding it. Then confirm IronOcr.License.IsLicensed returns true and tell me
where you put the call.
```
[IronOCR License Keys](https://ironsoftware.com/ocr/csharp/get-started/license-keys/) explains how to get a trial key and lists the configuration files from which IronOCR can read a key.
```text
Create Services/InvoiceReader.cs with a ReadTotal method that takes the path of a
scanned PDF, reads it with IronTesseract, finds the line containing Total due, and
returns the amount as a decimal with that line's confidence, or null when the
line is missing.
Then create Services/SearchablePdf.cs with a Convert method that writes a
searchable copy of a scanned PDF. Build and fix errors.
```
Codex generated two concise classes. The reader loads the scan into an input object with a using declaration, calls the engine's read method once, and iterates through the result's lines to find the total.
## How do you migrate an existing OCR implementation to IronOCR?
```text
Hand this to the explorer agent, since nothing should be written yet.
Imports/LegacyOcrService.cs currently reads scans with another OCR library.
1. List every read it performs, with the settings it uses (language, page
segmentation, image preprocessing, region, output format).
2. Map each setting to its IronOCR equivalent, citing the documentation page.
3. Do not write any code yet. Wait for my approval on the plan.
```
If an agent writes 400 lines before you approve the approach, you must review all 400 lines. A mapping table can be corrected with a single response.
After you approve the plan, keep the next request narrowly scoped.
```text
Put the worker agent on the approved plan.
Rewrite LegacyOcrService.cs to use IronOCR, keeping the existing public method
signatures so callers don't change. Before removing the old library, run both
implementations on every page in TestData/known/ and save a table of file,
expected values, and each engine's values to migration-check.md. Remove the old
library only if IronOCR returns the expected values at least as often, and
leave it in Git history only. Build and report the diff.
```
## How do you fix misread values through prompts?
The agent cannot see the paper original, so the prompt has to describe the error and, ideally, include the scans.
```text
I have attached one of the failing scans with codex --image, so look at it
rather than reasoning from file names.
Invoices in TestData/supplier-7/ return totals that are off by one digit in
about a third of cases. The scans are slightly rotated and have speckle from an
old scanner. Clean digital invoices read correctly.
Read InvoiceReader.cs and a sample of the scans. Explain the likely cause before
changing anything, then change the preprocessing only. Do not change how the
total is parsed. Report how many totals match before and after.
```
Refer to the [image orientation correction guide](https://ironsoftware.com/ocr/csharp/how-to/image-orientation-correction/) for rotation issues.
Missing languages are the other common case and need the same precision.
```text
German invoices throw LanguagePackException on the first read. Add what IronOCR
needs to read German, prove three German sample invoices return the expected
totals, and link me to the documentation page you used.
```
Language packs keep their own version numbers. The newest `IronOcr.Languages.German` is far behind the engine's 2026 releases, so an agent told to keep every Iron package on one version fails the restore until it accepts the mismatch. Say in the repository's agent rules that language packs are exempt.
## Which Tesseract settings should you change?
IronOCR provides access to Tesseract's controls through the engine's configuration object, and they help in fewer cases than their descriptions suggest.
```text
Totals in TestData/supplier-7/ now match after the preprocessing change.
Before anything else is tuned, measure the Tesseract settings IronOCR documents
for single fields: a character whitelist, single-line page segmentation, and a
crop to the amount. Apply one at a time on top of the current reader, report
the total read for every page, and keep a setting only if no page gets worse.
```
Codex kept the whitelist in `WhiteListCharacters`, which read 9 of 9 totals. `PageSegmentationMode` set to SingleLine read 0 of 9 and was dropped. A ContentArea crop read 9 of 9 supplier totals but 0 of 3 German, so it went too.
A later refactor combined this reader with a service that also reads invoice numbers, and the whitelist was removed.
In a separate probe on a tight crop around the $9,924.31 total, a whitelisted single-line read returned the right amount, and adding deskew and noise removal left an empty result or a stray 7. Apply filters to the whole page before cropping. Raw Tesseract variables without named properties are set via `Configuration.TesseractVariables`, a dictionary. Refer to the [advanced reading configuration guide](https://ironsoftware.com/ocr/csharp/how-to/ocr-configurations-for-advanced-reading/) for configuration properties and the [region guide](https://ironsoftware.com/ocr/csharp/how-to/ocr-region-of-an-image/) for cropping.
## How do you trace a failure across a whole import or into a container?
```text
Send the explorer agent through the import history first, without writing
anything.
Last month's import read 3,000 scanned invoices, and finance found 45 totals
that do not match the paper. Reprocessing one of those invoices gives the same
wrong total every time.
Investigate:
1. Read ImportService.cs and find how pages are loaded and preprocessed.
2. Identify what the misread invoices have in common.
3. Explain the cause before changing anything.
4. Then propose the minimal fix, and how you will prove the 45 now read correctly.
```
In our test, an explorer agent found that the importer rasterized pages at 96 DPI and recorded missing totals as $0.00. The agent then reread all 70 restored scans at 300 DPI and recovered 43 of 45, but two remained at zero and one previously correct page failed. The agent recommended a higher-resolution retry only when the first read returns zero. Refer to the [DPI settings guide](https://ironsoftware.com/ocr/csharp/how-to/dpi-setting/) and the [confidence guide](https://ironsoftware.com/ocr/csharp/how-to/tesseract-result-confidence/).
```text
Run this read-only until you have the cause.
This exception is thrown from InvoiceReader.ReadTotal in our Linux Docker
container but not on Windows:
[PASTE FULL EXCEPTION AND STACK TRACE HERE]
Check which IronOCR package the project references and whether it matches the
container's operating system, and whether IRONOCR_LICENSE_KEY reaches the
container. Explain the cause, then propose the change. Don't modify C# code
unless the cause is there.
```
The container needs the native dependencies the [Docker guide](https://ironsoftware.com/ocr/csharp/get-started/docker/) lists. That guide still installs `IronOcr`, which in the tested version ships only Windows native binaries.
## How do you turn one-off code into reusable, tested components?
```text
Put the worker agent on this.
Refactor InvoiceReader and SearchablePdf into an InvoiceOcrService registered
with dependency injection. It should read totals and invoice numbers from
scanned PDFs, flag any value whose line confidence is below 80, and produce
searchable copies. Keep the preprocessing choices in one place. Add XML doc
comments. Keep it under 120 lines. Before you finish, run the service over
every folder in TestData/ that has an expected.csv and confirm each total
still matches.
```
```text
Write xUnit tests for InvoiceOcrService covering: every page in TestData/known/
returns its expected invoice number and total, a page without a total returns
null rather than a guess, a searchable copy has a text layer, and a missing
license key throws a clear exception. Assert on extracted values, not on the
full text of the page.
```
For the missing-key scenario, test your own guard logic, as IronOCR's licensing exception is not a public type accessible to tests.
Keep recurring IronOCR questions in the repository skill rather than in `~/.codex/prompts/`, which OpenAI's [custom prompts](https://learn.chatgpt.com/docs/custom-prompts) page marks deprecated.
```text
$ironocr Read the IronOCR API reference for OcrInput and list every method that corrects
image problems, such as rotation, noise, and low resolution, then show which
ones this project already calls.
```
## What did the prompts produce in a real run?
We sent the prompts above to Codex in order, against a sample invoice project. The project is a console application with scanned PDFs, a legacy service using the open-source Tesseract wrapper, and three sets of pages with known values. After the run, an independent Release build, test suite, and probes across all three sets confirmed the results below.
- Supplier-7 totals rose from 6 of 9 to 9 of 9 with `Deskew` and `DeNoise`. Alone, Deskew read 9 of 9 and DeNoise 8 of 9.
- Both the legacy reader and IronOCR matched 10 of 10 in the migration check.
- With the German pack, 3 of 3 German totals read correctly and the supplier set stayed at 9 of 9.
- The 96-line service matched 10 of 10 known, 3 of 3 German and 9 of 9 supplier, and flagged 2 below 80 confidence.
- Tests passed 13 of 13.
- Codex ran 14 of 15 prompts with no build errors or manual code edits. The container prompt needs a real Linux stack trace and was not run, and the German samples and import history were added before their prompts.
- An earlier run failed three ways. Codex reported a 10 of 10 migration without running either engine, a refactor broke a known total, and a settings prompt assumed a filter the reader did not use.
This run's Codex version, model, timing and machine are in the shared [run record](/ocr/csharp/ai-agents/ai/#the-run-record).
## What carries over to the next project?
The [AI coding assistants guide](https://ironsoftware.com/ocr/csharp/ai-agents/ai/) adds a single acceptance prompt that takes an assistant from an empty folder to measured results, and the same prompt passed 10 of 10 in Codex during our tests.
---
## Troubleshooting
- [Apply a License Key in IronOCR](https://ironsoftware.com/ocr/csharp/troubleshooting/apply-a-license-key-in-ironocr/) if the code passes review but the run stops at the first read
- [Improve OCR Accuracy](https://ironsoftware.com/ocr/csharp/troubleshooting/improve-ocr-accuracy/) if the totals read from scans do not match the paper originals
- [Read Multiple Languages](https://ironsoftware.com/ocr/csharp/how-to/ocr-multiple-languages/) if Codex selects a language the repository has not installed
- [IronOCR on Docker](https://ironsoftware.com/ocr/csharp/get-started/docker/) if reads work on Windows and fail in a Linux container
---
## Questions?
If you have any questions, reach out to [support@ironsoftware.com](mailto:support@ironsoftware.com)
A common issue in initial AI-assisted OCR attempts is that developers paste incomplete scan importers into a chat, receive seemingly complete code, and later discover misread totals or incorrect configuration calls from other Tesseract wrappers. Such errors are costly with large APIs, as OCR engines with multiple filters, languages, and output formats present many opportunities for mistakes.
IronOCR reads text, barcodes, and table cells from scanned pages directly within your .NET application, locally and without a cloud service.
Quickstart
Install with NuGet
PM > Install-Package IronOcr
Install-Package IronOcr
Install IronOCR by running the command above in the NuGet Package Manager Console, or search for the package in the NuGet Package Manager.
Open Codex in a new console project and specify the desired output, and let Codex select the API calls.
$ironocr Add the IronOcr package, then update Program.cs to turn a scannedmulti-page PDF into a searchable one. Print the page count and the overallconfidence before the file is written. Read the license key from theIRONOCR_LICENSE_KEY environment variable. Then run dotnet build and fix anyerrors.
$ironocr Add the IronOcr package, then update Program.cs to turn a scanned
multi-page PDF into a searchable one. Print the page count and the overall
confidence before the file is written. Read the license key from the
IRONOCR_LICENSE_KEY environment variable. Then run dotnet build and fix any
errors.
Text
The $ironocr prefix loads IronOCR's skill.md, saved in the repository as .agents/skills/ironocr/SKILL.md, so Codex reads IronOCR's recipes and known fixes before it writes code.
Commit an AGENTS.md that names IronOCR as the repository's OCR engine
Start each Codex task on a clean branch and describe the pages and the values they hold
Let Codex edit files and run dotnet build, then review the diff before accepting it
Compare the extracted values with the known pages and verify each member in the API reference
What is ChatGPT Codex, and how does it fit into .NET OCR work?
ChatGPT Codex is OpenAI's coding agent. It can inspect code, edit files, and run commands in a repository. Install the CLI with npm install -g @openai/codex, as the Codex CLI documentation describes.
Codex's output may vary with each run, even for identical requests. The OCR engine must return the same text for the same scan every time, so use a maintained library and avoid allowing agents to improvise settings.
Preprocessing that is already built: skewed and noisy scans need correction before recognition. IronOCR's input object straightens skew, removes noise, and can also binarize and enhance resolution, and the image quality correction guide explains when the noise and resolution filters help.
PDFs without a text layer: IronOCR reads scanned PDFs and writes a copy with a real text layer, as the searchable PDF guide shows.
More than text: with Configuration.ReadBarCodes turned on, one read returns barcodes and QR codes alongside the text, and table reading is covered in the table reading guide.
Ongoing releases: the open-source Tesseract wrapper on NuGet was last updated in November 2022. IronOCR releases updates regularly, as its changelog shows.
What makes an IronOCR prompt effective?
An effective IronOCR prompt names the language and framework, where the code goes, the library version, the input and its fields, the expected output, and the constraints. For an invoice reader, that is C# on .NET 9, Services/InvoiceReader.cs, the IronOcr version in the .csproj, scanned PDF invoices with a Total due line, the total as a decimal with confidence, and no new packages.
Codex relies on its training data and any information you provide, so its knowledge of IronOCR's API may be out of date. OpenAI's research on hallucination traces invented answers to training and evaluation that reward guessing.
Put the OCR rules once in a committed AGENTS.md, which Codex reads before it starts work. IronOCR's llms.txt summarizes each documentation page in a line.
Create AGENTS.md at the repository root with an OCR section stating that thisproject uses IronOCR (NuGet package IronOcr, or IronOcr.Linux for Linux andDocker, namespace IronOcr) for all OCR work, that you must readhttps://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code and use onlyAPIs documented there, that https://ironsoftware.com/ocr/csharp/skill.md shouldbe loaded if the tooling supports skill files, that the license key comes fromthe IRONOCR_LICENSE_KEY environment variable and is never inlined, and that noother OCR engine or cloud OCR service may be added.
Create AGENTS.md at the repository root with an OCR section stating that this
project uses IronOCR (NuGet package IronOcr, or IronOcr.Linux for Linux and
Docker, namespace IronOcr) for all OCR work, that you must read
https://ironsoftware.com/ocr/csharp/llms.txt before writing OCR code and use only
APIs documented there, that https://ironsoftware.com/ocr/csharp/skill.md should
be loaded if the tooling supports skill files, that the license key comes from
the IRONOCR_LICENSE_KEY environment variable and is never inlined, and that no
other OCR engine or cloud OCR service may be added.
Text
How do you ask Codex to add IronOCR and read a first scanned invoice?
Add the IronOcr NuGet package to this project. Then show me the resultingPackageReference line from the .csproj and tell me which version was installed.Do not change any other package references.
Add the IronOcr NuGet package to this project. Then show me the resulting
PackageReference line from the .csproj and tell me which version was installed.
Do not change any other package references.
Text
The PackageReference line helps identify if an agent installed a different package with OCR or Tesseract in its name.
IronOCR does not offer a watermark mode. Without a license key, the first read throws a LicensingException.
Apply the IronOCR license key at application startup, before any other IronOCRcall, reading it from the IRONOCR_LICENSE_KEY environment variable rather thanhard-coding it. Then confirm IronOcr.License.IsLicensed returns true and tell mewhere you put the call.
Apply the IronOCR license key at application startup, before any other IronOCR
call, reading it from the IRONOCR_LICENSE_KEY environment variable rather than
hard-coding it. Then confirm IronOcr.License.IsLicensed returns true and tell me
where you put the call.
Text
IronOCR License Keys explains how to get a trial key and lists the configuration files from which IronOCR can read a key.
Create Services/InvoiceReader.cs with a ReadTotal method that takes the path of ascanned PDF, reads it with IronTesseract, finds the line containing Total due, andreturns the amount as a decimal with that line's confidence, or null when theline is missing.Then create Services/SearchablePdf.cs with a Convert method that writes asearchable copy of a scanned PDF. Build and fix errors.
Create Services/InvoiceReader.cs with a ReadTotal method that takes the path of a
scanned PDF, reads it with IronTesseract, finds the line containing Total due, and
returns the amount as a decimal with that line's confidence, or null when the
line is missing.
Then create Services/SearchablePdf.cs with a Convert method that writes a
searchable copy of a scanned PDF. Build and fix errors.
Text
Codex generated two concise classes. The reader loads the scan into an input object with a using declaration, calls the engine's read method once, and iterates through the result's lines to find the total.
How do you migrate an existing OCR implementation to IronOCR?
Hand this to the explorer agent, since nothing should be written yet.Imports/LegacyOcrService.cs currently reads scans with another OCR library.1. List every read it performs, with the settings it uses (language, page segmentation, image preprocessing, region, output format).2. Map each setting to its IronOCR equivalent, citing the documentation page.3. Do not write any code yet. Wait for my approval on the plan.
Hand this to the explorer agent, since nothing should be written yet.
Imports/LegacyOcrService.cs currently reads scans with another OCR library.
1. List every read it performs, with the settings it uses (language, page
segmentation, image preprocessing, region, output format).
2. Map each setting to its IronOCR equivalent, citing the documentation page.
3. Do not write any code yet. Wait for my approval on the plan.
Text
If an agent writes 400 lines before you approve the approach, you must review all 400 lines. A mapping table can be corrected with a single response.
After you approve the plan, keep the next request narrowly scoped.
Put the worker agent on the approved plan.Rewrite LegacyOcrService.cs to use IronOCR, keeping the existing public methodsignatures so callers don't change. Before removing the old library, run bothimplementations on every page in TestData/known/ and save a table of file,expected values, and each engine's values to migration-check.md. Remove the oldlibrary only if IronOCR returns the expected values at least as often, andleave it in Git history only. Build and report the diff.
Put the worker agent on the approved plan.
Rewrite LegacyOcrService.cs to use IronOCR, keeping the existing public method
signatures so callers don't change. Before removing the old library, run both
implementations on every page in TestData/known/ and save a table of file,
expected values, and each engine's values to migration-check.md. Remove the old
library only if IronOCR returns the expected values at least as often, and
leave it in Git history only. Build and report the diff.
Text
How do you fix misread values through prompts?
The agent cannot see the paper original, so the prompt has to describe the error and, ideally, include the scans.
I have attached one of the failing scans with codex --image, so look at itrather than reasoning from file names.Invoices in TestData/supplier-7/ return totals that are off by one digit inabout a third of cases. The scans are slightly rotated and have speckle from anold scanner. Clean digital invoices read correctly.Read InvoiceReader.cs and a sample of the scans. Explain the likely cause beforechanging anything, then change the preprocessing only. Do not change how thetotal is parsed. Report how many totals match before and after.
I have attached one of the failing scans with codex --image, so look at it
rather than reasoning from file names.
Invoices in TestData/supplier-7/ return totals that are off by one digit in
about a third of cases. The scans are slightly rotated and have speckle from an
old scanner. Clean digital invoices read correctly.
Read InvoiceReader.cs and a sample of the scans. Explain the likely cause before
changing anything, then change the preprocessing only. Do not change how the
total is parsed. Report how many totals match before and after.
Missing languages are the other common case and need the same precision.
German invoices throw LanguagePackException on the first read. Add what IronOCRneeds to read German, prove three German sample invoices return the expectedtotals, and link me to the documentation page you used.
German invoices throw LanguagePackException on the first read. Add what IronOCR
needs to read German, prove three German sample invoices return the expected
totals, and link me to the documentation page you used.
Text
Language packs keep their own version numbers. The newest IronOcr.Languages.German is far behind the engine's 2026 releases, so an agent told to keep every Iron package on one version fails the restore until it accepts the mismatch. Say in the repository's agent rules that language packs are exempt.
Which Tesseract settings should you change?
IronOCR provides access to Tesseract's controls through the engine's configuration object, and they help in fewer cases than their descriptions suggest.
Totals in TestData/supplier-7/ now match after the preprocessing change.Before anything else is tuned, measure the Tesseract settings IronOCR documentsfor single fields: a character whitelist, single-line page segmentation, and acrop to the amount. Apply one at a time on top of the current reader, reportthe total read for every page, and keep a setting only if no page gets worse.
Totals in TestData/supplier-7/ now match after the preprocessing change.
Before anything else is tuned, measure the Tesseract settings IronOCR documents
for single fields: a character whitelist, single-line page segmentation, and a
crop to the amount. Apply one at a time on top of the current reader, report
the total read for every page, and keep a setting only if no page gets worse.
Text
Codex kept the whitelist in WhiteListCharacters, which read 9 of 9 totals. PageSegmentationMode set to SingleLine read 0 of 9 and was dropped. A ContentArea crop read 9 of 9 supplier totals but 0 of 3 German, so it went too.
A later refactor combined this reader with a service that also reads invoice numbers, and the whitelist was removed.
In a separate probe on a tight crop around the $9,924.31 total, a whitelisted single-line read returned the right amount, and adding deskew and noise removal left an empty result or a stray 7. Apply filters to the whole page before cropping. Raw Tesseract variables without named properties are set via Configuration.TesseractVariables, a dictionary. Refer to the advanced reading configuration guide for configuration properties and the region guide for cropping.
How do you trace a failure across a whole import or into a container?
Send the explorer agent through the import history first, without writinganything.Last month's import read 3,000 scanned invoices, and finance found 45 totalsthat do not match the paper. Reprocessing one of those invoices gives the samewrong total every time.Investigate:1. Read ImportService.cs and find how pages are loaded and preprocessed.2. Identify what the misread invoices have in common.3. Explain the cause before changing anything.4. Then propose the minimal fix, and how you will prove the 45 now read correctly.
Send the explorer agent through the import history first, without writing
anything.
Last month's import read 3,000 scanned invoices, and finance found 45 totals
that do not match the paper. Reprocessing one of those invoices gives the same
wrong total every time.
Investigate:
1. Read ImportService.cs and find how pages are loaded and preprocessed.
2. Identify what the misread invoices have in common.
3. Explain the cause before changing anything.
4. Then propose the minimal fix, and how you will prove the 45 now read correctly.
Text
In our test, an explorer agent found that the importer rasterized pages at 96 DPI and recorded missing totals as $0.00. The agent then reread all 70 restored scans at 300 DPI and recovered 43 of 45, but two remained at zero and one previously correct page failed. The agent recommended a higher-resolution retry only when the first read returns zero. Refer to the DPI settings guide and the confidence guide.
Run this read-only until you have the cause.This exception is thrown from InvoiceReader.ReadTotal in our Linux Dockercontainer but not on Windows:[PASTE FULL EXCEPTION AND STACK TRACE HERE]Check which IronOCR package the project references and whether it matches thecontainer's operating system, and whether IRONOCR_LICENSE_KEY reaches thecontainer. Explain the cause, then propose the change. Don't modify C# codeunless the cause is there.
Run this read-only until you have the cause.
This exception is thrown from InvoiceReader.ReadTotal in our Linux Docker
container but not on Windows:
[PASTE FULL EXCEPTION AND STACK TRACE HERE]
Check which IronOCR package the project references and whether it matches the
container's operating system, and whether IRONOCR_LICENSE_KEY reaches the
container. Explain the cause, then propose the change. Don't modify C# code
unless the cause is there.
Text
The container needs the native dependencies the Docker guide lists. That guide still installs IronOcr, which in the tested version ships only Windows native binaries.
How do you turn one-off code into reusable, tested components?
Put the worker agent on this.Refactor InvoiceReader and SearchablePdf into an InvoiceOcrService registeredwith dependency injection. It should read totals and invoice numbers fromscanned PDFs, flag any value whose line confidence is below 80, and producesearchable copies. Keep the preprocessing choices in one place. Add XML doccomments. Keep it under 120 lines. Before you finish, run the service overevery folder in TestData/ that has an expected.csv and confirm each totalstill matches.
Put the worker agent on this.
Refactor InvoiceReader and SearchablePdf into an InvoiceOcrService registered
with dependency injection. It should read totals and invoice numbers from
scanned PDFs, flag any value whose line confidence is below 80, and produce
searchable copies. Keep the preprocessing choices in one place. Add XML doc
comments. Keep it under 120 lines. Before you finish, run the service over
every folder in TestData/ that has an expected.csv and confirm each total
still matches.
Text
Write xUnit tests for InvoiceOcrService covering: every page in TestData/known/returns its expected invoice number and total, a page without a total returnsnull rather than a guess, a searchable copy has a text layer, and a missinglicense key throws a clear exception. Assert on extracted values, not on thefull text of the page.
Write xUnit tests for InvoiceOcrService covering: every page in TestData/known/
returns its expected invoice number and total, a page without a total returns
null rather than a guess, a searchable copy has a text layer, and a missing
license key throws a clear exception. Assert on extracted values, not on the
full text of the page.
Text
For the missing-key scenario, test your own guard logic, as IronOCR's licensing exception is not a public type accessible to tests.
Keep recurring IronOCR questions in the repository skill rather than in ~/.codex/prompts/, which OpenAI's custom prompts page marks deprecated.
$ironocr Read the IronOCR API reference for OcrInput and list every method that correctsimage problems, such as rotation, noise, and low resolution, then show whichones this project already calls.
$ironocr Read the IronOCR API reference for OcrInput and list every method that corrects
image problems, such as rotation, noise, and low resolution, then show which
ones this project already calls.
Text
What did the prompts produce in a real run?
We sent the prompts above to Codex in order, against a sample invoice project. The project is a console application with scanned PDFs, a legacy service using the open-source Tesseract wrapper, and three sets of pages with known values. After the run, an independent Release build, test suite, and probes across all three sets confirmed the results below.
Supplier-7 totals rose from 6 of 9 to 9 of 9 with Deskew and DeNoise. Alone, Deskew read 9 of 9 and DeNoise 8 of 9.
Both the legacy reader and IronOCR matched 10 of 10 in the migration check.
With the German pack, 3 of 3 German totals read correctly and the supplier set stayed at 9 of 9.
The 96-line service matched 10 of 10 known, 3 of 3 German and 9 of 9 supplier, and flagged 2 below 80 confidence.
Tests passed 13 of 13.
Codex ran 14 of 15 prompts with no build errors or manual code edits. The container prompt needs a real Linux stack trace and was not run, and the German samples and import history were added before their prompts.
An earlier run failed three ways. Codex reported a 10 of 10 migration without running either engine, a refactor broke a known total, and a settings prompt assumed a filter the reader did not use.
This run's Codex version, model, timing and machine are in the shared run record.
What carries over to the next project?
The AI coding assistants guide adds a single acceptance prompt that takes an assistant from an empty folder to measured results, and the same prompt passed 10 of 10 in Codex during our tests.
Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.
Install with NuGet
