BoreholeAI Python SDK

Geotechnical Borehole Log Digitisation

Website · Get API Key · Contact

Upload borehole log PDFs or images, get structured ground profiles, test data, and annotated PDFs.

Background

The problem: Geotechnical engineers routinely extract data from borehole log PDFs manually — reading material descriptions, depths, test results, and keying them into spreadsheets or AGS files. On a typical project with dozens of logs, this takes days. On larger projects, it can take weeks.

Why it matters: This matters beyond individual project efficiency. Globally, millions of dollars are spent each year on new ground investigations to understand subsurface conditions — but much of this work has already been done before. Valuable geological and geotechnical records from past projects sit in libraries as old hard copies, in consultancy archives, or on digital platforms that aren't searchable or interoperable. Over time, these reports get misplaced, disposed of, or locked behind organisational boundaries. When that happens, the cycle of discovery starts again from scratch.

What others have done: Countries like Denmark, the Netherlands, Switzerland, and the UK have recognised this problem and built centralised, publicly accessible geotechnical databases — some legislated as far back as 1926. In Australia, there is no equivalent national system. Geotechnical data is kept in isolation by individual consultancies, with no regulated or standardised approach to data collection and sharing after project completion. For more on this challenge and what other countries have achieved, see the Churchill Trust report on geotechnical data capture.

Our approach: We built BoreholeAI because we believe that better geotechnical data infrastructure starts with making it easier to get data out of the documents where it's currently trapped. BoreholeAI reads borehole log PDFs (scanned or digital) and extracts the geotechnical data — with depth and spatial awareness — into structured formats like Excel and AGS.

What It Does

Extracts:

• Ground profile — material descriptions, depths, geology, consistency/density
• Test data — SPT, UCS, Is50, PP, groundwater levels
• Borehole metadata — hole ID, location, dates, drilling method

Outputs:

• Borehole_ground_profile.xlsx — structured ground profile table (pass macro_button=True for a .xlsm with a "Regenerate derived tabs" macro button that rebuilds the derived tabs after hand corrections)
• Borehole_test_data.xlsx — all test results in tabular format
• Borehole_ags4.ags — industry-standard AGS4 data transfer file
• Borehole_data.json — the same extracted data as machine-readable JSON
• *_annotated.pdf — original document with extracted regions highlighted

Examples

See the quickstart notebook for an interactive walkthrough, or follow the steps below.

Installation

pip install boreholeai

Quick Start

import os

from boreholeai import BoreholeAI

# Get your API key at: https://boreholeai.com/app/settings/api-keys
client = BoreholeAI(api_key=os.environ["BOREHOLEAI_API_KEY"])

# Process a single borehole log
result = client.process_documents("BH01.pdf", output_dir="./results")

print(f"Status: {result.status}")
print(f"Pages processed: {result.num_pages}")
for f in result.files:
    print(f"  {f.filename}")

Results land in output_dir, with the annotated PDF under annotated_pdf/. When everything has completed, a run at an interactive terminal asks whether to clean up its resume state — answer y for a one-shot run, or see Incremental Runs for why you might keep it.

Folder / Batch Processing

Pass a directory path to process multiple files together. The SDK processes files in parallel and merges the outputs locally into a single ground profile Excel, test data Excel, AGS file, and data JSON. Annotated PDFs are collected in an annotated_pdf/ subfolder, one per input file.

result = client.process_documents(
    "./borehole_logs/",
    output_dir="./results",
)

# Output:
#   Borehole_ground_profile_merged.xlsx   (.xlsm with macro_button=True)
#   Borehole_test_data_merged.xlsx
#   Borehole_ags4_merged.ags
#   Borehole_data_merged.json
#   annotated_pdf/
#     BH01_annotated.pdf            (one per input file)
#     BH02_annotated.pdf
#     BH03_annotated.pdf

A single-file run keeps the original filenames (no _merged suffix).

The ground profile workbook ships as a plain macro-free .xlsx by default. Pass macro_button=True to process_documents for a macro-enabled .xlsm whose Processing Info sheet carries a "Regenerate derived tabs" button that rebuilds the Geology / Consistency_Density / USCS tabs from a hand-corrected Material tab.

Resume After Interrupt

If processing is interrupted (Ctrl-C, network drop, laptop sleep), simply re-run with the same output_dir. The SDK persists per-file state to .boreholeai_manifest.json and skips work that's already done.

# First run — interrupted halfway through 100 files
client.process_documents("./logs/", output_dir="./results")

# Same call, same output_dir — picks up where it left off
client.process_documents("./logs/", output_dir="./results")

Incremental Runs

The SDK keeps its resume state (.boreholeai_manifest.json plus a .boreholeai_workdir/ cache) after a successful run, so you can add more files to the same folder later and simply re-run: completed files are skipped, only new or changed files are processed, and the merged outputs are regenerated to cover everything. Each cache subfolder is labelled <input filename> <job_id> (for example, BH01.pdf 00000000-0000-4000-8000-000000000000) so it can be identified without opening the manifest.

A file whose content changed on disk is detected and re-processed automatically; to force a single file to re-run by hand, set "reprocess": true on its entry in .boreholeai_manifest.json. A forced reprocess creates a new server job, replaces the active job ID, resets the active download/progress state, and removes the prior job's client-side cache folder once the replacement job is accepted. The old server-side job is not deleted by this setting.

Once every file has completed, a run at an interactive terminal asks whether to clean up the resume state. You can also decide in code and skip the question:

# Keep state, never ask — incremental mode for scripts
client.process_documents("./logs/", output_dir="./results", finalise_and_cleanup=False)

# Clean up on success, never ask — one-shot mode
client.process_documents("./logs/", output_dir="./results", finalise_and_cleanup=True)

Each output_dir is tied to one input folder — re-using a kept output_dir with a different input folder raises an error instead of silently mixing results.

Partial Failure Handling

If some files fail server-side processing (bad scan, unreadable layout, etc.), the rest are merged normally and the failed files are reported via result.failures with a "partial" status; if every file fails the status is "failed". Failed files are retried automatically the next time you re-run with the same output_dir.

A merge_warnings.txt file is written to output_dir only when warnings occur during merge (e.g. a job missing one of its result files).

Supported File Types

• PDF (.pdf)
• PNG (.png)
• JPEG (.jpg, .jpeg)
• TIFF (.tif, .tiff)
• WebP (.webp)

API Key

Get your API key from the BoreholeAI dashboard.

Keep it out of your source — read it from the environment:

export BOREHOLEAI_API_KEY="bhai_xxx"

import os

client = BoreholeAI(api_key=os.environ["BOREHOLEAI_API_KEY"])

Accuracy

BoreholeAI uses a sophisticated multi-agent, multi-stage agentic system that combines engineering deterministic algorithms, customized deep learning models, and computer vision with AI-assisted document understanding. Your documents are never read directly by AI models — we apply an OCR intermediary layer so that AI only works with extracted text and layout information, never with your original files and hence ensuring data security. The structured output is driven by spatial reasoning and rule-based logic, not generative models.

The system handles complex layouts, varying scales, multi-page logs, and inconsistent formatting.

We have tested extensively across a wide range of publicly available borehole log formats and consistently achieve 95-100% accuracy. We are grateful to the Queensland Geotechnical Database (QGD) for making their data publicly available — their collection of real-world borehole logs has been invaluable for testing and validating the system.

That said, borehole logs vary significantly in layout and formatting. If you find an inaccuracy or an extraction issue, please let us know — every report helps us improve the system.

Expected input: Borehole log PDFs, scanned copies, handwritten logs, or photos taken directly on site (e.g. a phone camera shot of a printed or handwritten log).

Current Scope and Limitations

• Standard alignment: Not limited to Australian/NZ logs. Validated most extensively against Australian Standard AS 1726 formats; logs following other national standards are supported. If your logs use a non-standard or customised layout, contact us.
• Document types: Borehole logs (BH), pavement core logs (PCP), and test pit logs (TP). Other geotechnical documents (e.g. CPT plots, lab reports) are not currently supported.
• Languages: Not limited to English — logs in other languages are supported.
• Units: Metric only — depths and dimensions must be in metres. Logs in feet or other imperial units are not currently supported.
• Scans and photos: Scanned copies and photos taken directly (e.g. a phone camera shot of a printed or handwritten log) are both supported. Keep the page flat and roughly square-on; heavily tilted or skewed captures reduce accuracy.
• Watermarks: PDFs with heavy watermarks, especially tilted ones, will reduce accuracy — particularly for strength and test data extraction. Upload a clean copy where possible.
• Handwriting: Handwritten logs are supported. Extremely unclear handwriting may still affect results.
• File size: Maximum 20 MB per file.

Credits

BoreholeAI uses a credit system (1 credit = 1 page) to cover the computational cost of running the AI models. Every new account (individuals) receives free credits to get started, and additional free credits are available on request — just get in touch.

For those who'd like to support the ongoing development of the project and help keep it running, credits can also be purchased here. This is entirely optional — the goal is to make geotechnical data more accessible, and we'd rather people use the tool than not.

Contact us

Enterprise

We understand that many organisations have strict data governance requirements and cannot send documents to external services. BoreholeAI can be deployed within your own infrastructure — on-premise or in your private cloud — so that your data never leaves your environment.

If this is a requirement for your team, contact us to discuss deployment options.

Disclaimer

While every effort has been made to ensure accuracy and reliability, BoreholeAI is a tool to assist — not replace — professional judgement. It is the user's responsibility to verify that all extracted data is accurate and fit for their intended purpose, including compliance with applicable design specifications, standards, and regulatory requirements.

License

Apache-2.0